@fungi.computer/parakeet 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,187 @@
-# Temporary Holding Version
+# Parakeet (`@fungi.computer/parakeet`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Parakeet renders an Agent conversation from a typed Shiitake Session. Browser
+hosts use its React view; terminal hosts use its headless hooks to render the
+same history, composer and status through their own UI.
+
+Website hosts mount the same `Parakeet` component inside an isolated iframe. A
+visitor-session adapter supplies the visitor's scoped Session read, watch and
+prompt commands; credentials and admission remain with the host.
+`markdownPolicy="visitor"` renders Markdown links without loading images or
+unsafe destinations. A prompt recorded for a human returns `status: "recorded"`,
+not a fabricated Agent-work acceptance. Closing the view stops observation, not
+the Agent's work. Pass `visitor={{ agentName: "Front Desk" }}` to hide model,
+usage and command controls. Slash-prefixed text remains a normal visitor
+message; the visitor mode does not register or execute slash commands.
+
+## Set up
+
+Install `@fungi.computer/parakeet` from its package tarball. It requires a
+compatible React and React DOM pair, TanStack Query and an authorized Session
+supplied by the host. The manifest supports React 18.2 or 19.2 and later within
+those major versions. Build the dependency closure from the repository root:
+
+```sh
+pnpm turbo:run run build --filter=@fungi.computer/parakeet
+```
+
+Browser hosts import `@fungi.computer/parakeet/styles.css` once. It includes the
+Caps/Stipe foundation and conversation utilities. Do not also load
+`@fungi.computer/caps/styles.css` in that document. Import Caps' `fonts.css`
+separately when using its bundled fonts, with font URLs handled by your bundler.
+
+A host compiling its own Tailwind utilities uses the `/tailwind.css` source
+instead and supplies its own `@source`. The built stylesheet cannot scan your
+host's additional classes.
+
+## Quick start in a browser
+
+Illustrative: your host supplies the authorized `ParakeetSession` and a browser
+bundler that handles CSS. This component owns its query cache and clears it on
+unmount. It does not create an Agent, sign in or grant tools.
+
+```tsx
+import { useEffect, useState } from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { Parakeet, type ParakeetSession } from "@fungi.computer/parakeet";
+import "@fungi.computer/parakeet/styles.css";
+
+export function Conversation({ session }: { session: ParakeetSession }) {
+  const [queryClient] = useState(() => new QueryClient());
+  useEffect(() => () => queryClient.clear(), [queryClient]);
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Parakeet session={session} />
+    </QueryClientProvider>
+  );
+}
+```
+
+Parakeet never reads a message's host metadata itself. To show who wrote a line,
+pass `authorOf`: your reading of that metadata into a `ParakeetAuthor`
+(`{ id, name }`). A Fungi app passes `messageAuthor` from
+`@fungi.computer/hub-client/message-meta`; without it, lines show no author.
+
+The view presents the Session's observed history, live work, composer and
+errors. Screen readers receive the same Session status as the composer footer
+through a hidden polite live region; streamed transcript tokens are outside that
+region. The Session transport stays owned by the caller. Releasing observation
+does not cancel accepted work or close a borrowed Agent. When replacing a
+Session, provide its new handle rather than copying a snapshot into another
+writable store.
+
+The [standalone composer tests](test/standalone-composer.test.tsx) exercise the
+provider, query cache, observations and prompt admission with typed fixtures.
+The browser contract uses the real component with a fixture Session. A fake
+Session checks the component, not hosted authentication or a model provider.
+
+## Core concepts
+
+| Surface                             | What it owns                                                                                        |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `Parakeet`                          | The browser conversation, including provider and view.                                              |
+| `ParakeetProvider` / `ParakeetView` | Separate composition when the host needs custom controls in the same conversation scope.            |
+| `useTimeline()`                     | Durable history and the replaceable live tail, bounded history paging and model/usage presentation. |
+| `useComposer()`                     | Draft, submission, pending work, cancellation and retry controls.                                   |
+| `useStatus()`                       | Observed work and connection state, including goal controls.                                        |
+| `useMarkdown(content)`              | Parsed chat Markdown for custom and terminal renderers.                                             |
+
+Both composition forms require the host's `QueryClientProvider`. `Parakeet`
+takes the `session` directly. With separate composition, pass `session` to
+`ParakeetProvider` and put `ParakeetView` and custom hook consumers beneath it.
+Pass `commands` and presentation props to the view, not the provider.
+
+`Parakeet` and `ParakeetView` share these optional presentation props:
+
+| Prop                        | Contract                                                                |
+| --------------------------- | ----------------------------------------------------------------------- |
+| `composerActionVariant`     | `"primary"` or `"outline"`.                                             |
+| `renderToolActions`         | Renders host actions for a completed `ToolItem`.                        |
+| `renderAssistantAttachment` | Receives the original settled reply text.                               |
+| `formatAssistantText`       | Changes displayed reply text without changing the attachment input.     |
+| `onLink`                    | Receives a transcript URL; return `true` to prevent browser navigation. |
+| `empty`                     | Replaces the empty conversation content.                                |
+
+Import renderer-neutral hooks from `/headless` in the terminal. That entry
+avoids loading the DOM presentation, Caps and Sprite closure. The root exports
+those same hooks for browser callers. They share the Session's TanStack Query
+cache. Derived atoms select observed values rather than duplicating Session
+truth. History pages share the host's cache by Session address and survive
+provider remounts until that cache expires. Paging retains four 100-message
+pages, with bounded return cursors for the Session's before-only read API.
+Jumping to latest cancels the outstanding history fetch and clears that shared
+history window; the live observation remains separate.
+
+Tool calls are grouped in the shared projection. Browser and terminal renderers
+receive the same typed summaries, error-first sections and edit diffs.
+Disclosure state belongs to the view. A goal row displays the committed goal;
+pausing it leaves current accepted work running. Idle conversation state does
+not mean the goal is complete.
+
+## Commands and errors
+
+A host may supply its Whistle runtime through `commands`. Parakeet builds the
+slash registry from that host, its built-ins and advertised extension catalogs.
+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.
+
+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.
+
+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.
+
+## API and examples
+
+Use the [generated API reference](docs/api/README.md) and
+[exports](package.json). The root owns browser components, `/headless` owns
+shared hooks, `/slash` owns command grammar, and `/agent-head` owns Agent
+appearance contracts.
+
+[Transcript stories](workbench/transcript.stories.tsx) show settled, streaming
+and failed replies. [Tool group stories](workbench/tool-groups.stories.tsx) show
+shared projections. [Slash parity tests](test/slash-parity.test.tsx) check the
+common interaction contract.
+[Headless surface tests](test/headless-surface.test.ts) check that non-browser
+imports stay independent of the DOM view.
+
+## Contribute and license
+
+Add a fixture case to the nearest conversation, command or rendering test. From
+the repository root:
+
+```sh
+pnpm --dir packages/parakeet run test
+pnpm --dir packages/parakeet run browser:contract
+pnpm --dir packages/parakeet run docs
+```
+
+The browser contract needs the repository's configured browser tooling. Unit
+checks do not replace that proof. Parakeet is MIT licensed; see
+[LICENSE](LICENSE).
+
+## TypeScript consumer dependencies
+
+Install `@modelcontextprotocol/sdk@1.25.2` alongside this package when compiling
+its complete public declarations. The shared provider SDK imports those types
+through an optional peer; the packed consumer supplies it explicitly. This does
+not require a provider account or make a provider call.
+
+## Packed consumer readiness
+
+Run `pnpm run build`, `pnpm run pack` and `pnpm run stranger` in this package.
+The maintained stranger proof installs only package tarballs into a fresh npm
+consumer, checks the exact shipped files, runs the public runtime fixture and
+compiles every JavaScript entrypoint with strict NodeNext and no library-check
+skip. This qualification does not publish npm releases or push a repository
+split.
+
+See [LICENSE](LICENSE) for the license and the package manifest for its public
+repository destination.

package/dist/account-commands.d.ts

@@ -0,0 +1,102 @@
+import { type WhistleContribution, type WhistleContributionLease, type WhistleInteraction, type WhistleRuntime } from "@fungi.computer/whistle";
+/** How a person proves they may use a provider: an API key or their subscription sign-in. */
+export type LoginMethodKind = "api_key" | "subscription";
+/** One sign-in method a provider offers, labelled by its owner. */
+export type LoginMethod = Readonly<{
+    /** API key or subscription sign-in. */
+    kind: LoginMethodKind;
+    /** Provider-supplied label, e.g. "Anthropic API key". */
+    label: string;
+}>;
+/** One model provider in the registry. Names come from data, never code. */
+export type LoginProvider = Readonly<{
+    /** Stable provider identity, e.g. a Pi provider id. */
+    id: string;
+    /** Provider-supplied display name. */
+    name: string;
+    /** Sign-in methods this provider offers. */
+    methods: readonly LoginMethod[];
+}>;
+/** Where the credential will be used: the person's machine or Fungi's servers. */
+export type LoginHost = "local" | "hosted";
+/** Whose credential it is: one person, or a Team. */
+export type LoginScope = "user" | "team";
+/**
+ * The credential policy owner's decision, the same shape as
+ * `@fungi.computer/veil/model-credentials` `loginAllowed`. Login offers only
+ * what it permits.
+ */
+export type LoginPolicy = Readonly<{
+    /** Whether this method may be offered for this provider, host and scope. */
+    loginAllowed: (request: Readonly<{
+        providerId: string;
+        method: LoginMethodKind;
+        host: LoginHost;
+        scope: LoginScope;
+    }>) => boolean;
+}>;
+/** The providers and methods one surface may offer, in display order. */
+export declare function loginRegistry(providers: readonly LoginProvider[], options: Readonly<{
+    policy: LoginPolicy;
+    host: LoginHost;
+    scope: LoginScope;
+}>): readonly LoginProvider[];
+/** A configured provider reported by the credential owner, without secrets. */
+export type ProviderAccess = Readonly<{
+    /** Stable registry identity. */
+    providerId: string;
+    /** Provider-owned display label. */
+    providerName: string;
+    /** The configured credential kind. */
+    type: "oauth" | "api_key";
+}>;
+/** The credential owner behind the account commands. */
+export type AccountOwner = Readonly<{
+    /** Host-owned popular order, shared by account and model choices. */
+    popularProviderIds: readonly string[];
+    /** Configured provider access from the credential owner's parsed status. */
+    access: (signal: AbortSignal) => Promise<readonly ProviderAccess[]>;
+    /** Every provider the owner can sign in to, before policy. */
+    providers: (signal: AbortSignal) => Promise<readonly LoginProvider[]>;
+    /** Run the provider's own sign-in; it may prompt and notify. */
+    login: (request: Readonly<{
+        providerId: string;
+        method: LoginMethodKind;
+        /** Provider-specific choice, e.g. a device-code flow. */
+        option?: string;
+    }>, interaction: WhistleInteraction) => Promise<void>;
+    /** Remove the provider's stored credential. */
+    logout: (providerId: string, interaction: WhistleInteraction) => Promise<void>;
+    /** A short human summary of configured providers. */
+    status: (signal: AbortSignal) => Promise<string>;
+}>;
+/** Contribution identity and the policy context for account commands. */
+export type AccountCommandOptions = Readonly<{
+    /** Host source that owns the contribution lease. */
+    sourceId: string;
+    /** Namespace for the account commands. */
+    namespace: string;
+    /** Where credentials signed in here will be used. */
+    host: LoginHost;
+    /** Whose credentials they are. */
+    scope: LoginScope;
+    /** The credential policy owner's decision. */
+    policy: LoginPolicy;
+}>;
+/** One account owner and its credential policy context for an interactive model picker. */
+export type ModelAccountContext = Pick<AccountCommandOptions, "policy" | "host" | "scope"> & Readonly<{
+    /** Existing credential owner, also used by the account commands. */
+    owner: AccountOwner;
+}>;
+/** Run the existing provider-owned sign-in after the caller applies credential policy. */
+export declare function signInProvider(owner: AccountOwner, provider: LoginProvider, interaction: WhistleInteraction, request?: Readonly<{
+    method?: LoginMethodKind | undefined;
+    option?: string | undefined;
+}>): Promise<void>;
+/**
+ * Provider-agnostic account commands. Every question and status update is a
+ * Whistle interaction, so any client that renders interactions renders login.
+ */
+export declare function accountCommandDefinitions(owner: AccountOwner, options: AccountCommandOptions): WhistleContribution["commands"];
+/** Contribute the account commands as one lease. */
+export declare function contributeAccountCommands(runtime: Pick<WhistleRuntime, "contribute">, owner: AccountOwner, options: AccountCommandOptions): WhistleContributionLease;

package/dist/account-commands.js

@@ -0,0 +1,239 @@
+import { WhistleActionError, } from "@fungi.computer/whistle";
+import { z } from "zod";
+import { providerChoices } from "./provider-choices.js";
+/** The providers and methods one surface may offer, in display order. */
+export function loginRegistry(providers, options) {
+    return providers
+        .map((provider) => ({
+        ...provider,
+        methods: provider.methods.filter((method) => options.policy.loginAllowed({
+            providerId: provider.id,
+            method: method.kind,
+            host: options.host,
+            scope: options.scope,
+        })),
+    }))
+        .filter((provider) => provider.methods.length > 0)
+        .sort((left, right) => left.name.localeCompare(right.name) || left.id.localeCompare(right.id));
+}
+const loginArguments = z.strictObject({
+    providerId: z.string().min(1).max(200).optional(),
+    method: z.enum(["api_key", "subscription"]).optional(),
+    option: z.string().min(1).max(200).optional(),
+});
+const loginArgumentsSchema = z
+    .record(z.string(), z.json())
+    .parse(structuredClone(z.toJSONSchema(loginArguments)));
+const logoutArguments = z.strictObject({
+    providerId: z.string().min(1).max(200).optional(),
+});
+const logoutArgumentsSchema = z
+    .record(z.string(), z.json())
+    .parse(structuredClone(z.toJSONSchema(logoutArguments)));
+function methodDescription(method, provider) {
+    return method.kind === "api_key"
+        ? "Paste an API key you created"
+        : `Sign in with your ${provider.name} account`;
+}
+function requireInteraction(input) {
+    if (input.interaction === undefined)
+        throw new WhistleActionError("interaction_required", "Signing in needs an interactive client.");
+    return input.interaction;
+}
+async function chooseProvider(providers, requested, interaction, message, choices) {
+    if (requested !== undefined) {
+        const provider = providers.find((candidate) => candidate.id === requested);
+        if (provider === undefined)
+            throw new WhistleActionError("unknown_provider", `${requested} is not available here.`);
+        return provider;
+    }
+    if (providers.length === 0)
+        throw new WhistleActionError("no_providers", "No model providers are available here.");
+    const id = await interaction.prompt({
+        type: "choice",
+        message,
+        collapsedGroup: "More providers",
+        options: choices,
+    });
+    const provider = providers.find((candidate) => candidate.id === id);
+    if (provider === undefined)
+        throw new WhistleActionError("unknown_provider", `${id} is unavailable.`);
+    return provider;
+}
+async function chooseMethod(provider, requested, interaction) {
+    if (requested !== undefined) {
+        const method = provider.methods.find((one) => one.kind === requested);
+        if (method === undefined)
+            throw new WhistleActionError("method_unavailable", `${provider.name} does not offer that sign-in method here.`);
+        return method;
+    }
+    const [only, ...rest] = provider.methods;
+    if (only !== undefined && rest.length === 0)
+        return only;
+    const kind = await interaction.prompt({
+        type: "choice",
+        message: `How do you want to sign in to ${provider.name}?`,
+        options: provider.methods.map((method) => ({
+            value: method.kind,
+            label: method.label,
+            description: methodDescription(method, provider),
+        })),
+    });
+    const method = provider.methods.find((one) => one.kind === kind);
+    if (method === undefined)
+        throw new WhistleActionError("method_unavailable", "Choose a listed method.");
+    return method;
+}
+/** Run the existing provider-owned sign-in after the caller applies credential policy. */
+export async function signInProvider(owner, provider, interaction, request = {}) {
+    const method = await chooseMethod(provider, request.method, interaction);
+    interaction.notify({
+        type: "progress",
+        message: `Signing in to ${provider.name}…`,
+    });
+    await 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}.`,
+    });
+}
+async function signOutProvider(owner, provider, interaction) {
+    const confirmed = await interaction.prompt({
+        type: "confirmation",
+        message: `Sign out of ${provider.name}? Local Sessions stop using this account.`,
+        confirmLabel: "Sign out",
+        cancelLabel: "Keep signed in",
+    });
+    if (!confirmed)
+        return;
+    await owner.logout(provider.id, interaction);
+    interaction.notify({
+        type: "success",
+        message: `Signed out of ${provider.name}.`,
+    });
+}
+/** Cancelling a sign-in is an ordinary ending, not a failure. */
+async function unlessCancelled(interaction, work) {
+    try {
+        await work();
+        return true;
+    }
+    catch (cause) {
+        if (interaction.signal.aborted)
+            return false;
+        throw cause;
+    }
+}
+/**
+ * Provider-agnostic account commands. Every question and status update is a
+ * Whistle interaction, so any client that renders interactions renders login.
+ */
+export function accountCommandDefinitions(owner, options) {
+    const { policy } = options;
+    return [
+        {
+            id: "account",
+            title: "Model accounts",
+            category: "Settings",
+            projections: {
+                help: { order: 10 },
+                slash: { aliases: ["account"], order: 10 },
+            },
+            handler: async (input) => {
+                const summary = await owner.status(input.signal ?? new AbortController().signal);
+                input.interaction?.notify({ type: "info", message: summary });
+                return summary;
+            },
+        },
+        {
+            id: "login",
+            title: "Sign in to a model provider",
+            category: "Settings",
+            projections: {
+                help: { order: 11 },
+                menu: { order: 11 },
+                palette: { order: 11 },
+                slash: { aliases: ["login"], order: 11 },
+            },
+            action: { inputSchema: loginArgumentsSchema },
+            handler: async (input) => {
+                const interaction = requireInteraction(input);
+                const request = loginArguments.parse(input.arguments ?? {});
+                await unlessCancelled(interaction, async () => {
+                    const registry = loginRegistry(await owner.providers(interaction.signal), { policy, host: options.host, scope: options.scope });
+                    const access = request.providerId === undefined
+                        ? await owner.access(interaction.signal)
+                        : [];
+                    const provider = await chooseProvider(registry, request.providerId, interaction, "Choose a model provider", providerChoices(registry, access, owner.popularProviderIds, "login"));
+                    if (request.providerId === undefined &&
+                        access.some((item) => item.providerId === provider.id)) {
+                        const action = await interaction.prompt({
+                            type: "choice",
+                            message: provider.name,
+                            options: [
+                                { value: "switch", label: "Switch account" },
+                                { value: "logout", label: "Sign out" },
+                            ],
+                        });
+                        if (action === "logout") {
+                            await signOutProvider(owner, provider, interaction);
+                            return;
+                        }
+                    }
+                    await signInProvider(owner, provider, interaction, request);
+                });
+            },
+        },
+        {
+            id: "logout",
+            title: "Sign out of a model provider",
+            category: "Settings",
+            projections: {
+                help: { order: 12 },
+                palette: { order: 12 },
+                slash: { aliases: ["logout"], order: 12 },
+            },
+            action: { inputSchema: logoutArgumentsSchema },
+            handler: async (input) => {
+                const interaction = requireInteraction(input);
+                const request = logoutArguments.parse(input.arguments ?? {});
+                await unlessCancelled(interaction, async () => {
+                    // Only providers the credential owner reports as signed in can be signed out of.
+                    const signedIn = (await owner.access(interaction.signal))
+                        .map((access) => ({
+                        id: access.providerId,
+                        name: access.providerName,
+                        methods: [],
+                    }))
+                        .sort((left, right) => left.name.localeCompare(right.name));
+                    if (signedIn.length === 0) {
+                        interaction.notify({
+                            type: "info",
+                            message: await owner.status(interaction.signal),
+                        });
+                        return;
+                    }
+                    const provider = await chooseProvider(signedIn, request.providerId, interaction, "Sign out of which provider?", signedIn.map((provider) => ({
+                        value: provider.id,
+                        label: provider.name,
+                    })));
+                    await signOutProvider(owner, provider, interaction);
+                });
+            },
+        },
+    ];
+}
+/** Contribute the account commands as one lease. */
+export function contributeAccountCommands(runtime, owner, options) {
+    return runtime.contribute({
+        sourceId: options.sourceId,
+        namespace: options.namespace,
+        commands: accountCommandDefinitions(owner, options),
+    });
+}

package/dist/agent-head.d.ts

@@ -0,0 +1,4 @@
+export { AgentHead } from "./components/AgentHead.js";
+export type { AgentHeadActivity } from "./components/AgentHead.js";
+export { ShiitakeAvatar } from "./components/ShiitakeAvatar.js";
+export type { AvatarState } from "./components/ShiitakeAvatar.js";

package/dist/agent-head.js

@@ -0,0 +1,2 @@
+export { AgentHead } from "./components/AgentHead.js";
+export { ShiitakeAvatar } from "./components/ShiitakeAvatar.js";

package/dist/client-contributions.d.ts

@@ -0,0 +1,20 @@
+import type { ClientContributionV1 } from "@fungi.computer/shiitake/client-entry";
+import type { ParakeetCommandRuntime } from "./commands/use-slash-commands.js";
+/** Ordinary advertised actions over the current admitted rows and observation. */
+export declare function useClientActions(commands: ParakeetCommandRuntime): {
+    /** Current Session-owned state of admitted action intents. */
+    state: ReadonlyMap<{
+        readonly label: string;
+        readonly id: string;
+        readonly input?: {
+            readonly [x: string]: import("effect/Schema").Json;
+        } | undefined;
+    }, Readonly<{
+        pending: boolean;
+        error?: string;
+    }>>;
+    /** Observation is live and this Session's action owner is attached. */
+    enabled: boolean;
+    /** Execute an admitted intent through its owning advertised command. */
+    execute: (entryId: string, action: NonNullable<ClientContributionV1["waiting"]>["cancel"], waiting?: boolean) => Promise<void>;
+};

package/dist/client-contributions.js

@@ -0,0 +1,41 @@
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { useClientContributions, useParakeetInteractions, useParakeetSession, useStatus, } from "./conversation.js";
+import { createClientActions, } from "./core/client-actions.js";
+const emptyActions = new Map();
+const noActions = () => emptyActions;
+const noSubscription = () => () => undefined;
+/** Ordinary advertised actions over the current admitted rows and observation. */
+export function useClientActions(commands) {
+    const contributions = useClientContributions();
+    const { observation } = useStatus();
+    const interactions = useParakeetInteractions();
+    const session = useParakeetSession();
+    const [owner, setOwner] = useState();
+    // This mutable input carries committed slots, never an optimistic projection.
+    const input = useRef({ contributions, observation });
+    input.current = { contributions, observation };
+    useEffect(() => {
+        const selected = createClientActions({
+            commands,
+            contributions: () => input.current.contributions,
+            online: () => input.current.observation.status === "live",
+            interactions,
+        });
+        setOwner(selected);
+        return () => {
+            selected.dispose();
+        };
+    }, [commands, interactions, session]);
+    useEffect(() => {
+        owner?.refresh();
+    }, [owner, contributions]);
+    const state = useSyncExternalStore(owner?.subscribe ?? noSubscription, owner?.snapshot ?? noActions, owner?.snapshot ?? noActions);
+    return {
+        /** Current Session-owned state of admitted action intents. */
+        state,
+        /** Observation is live and this Session's action owner is attached. */
+        enabled: owner !== undefined && observation.status === "live",
+        /** Execute an admitted intent through its owning advertised command. */
+        execute: (entryId, action, waiting = false) => owner?.execute(entryId, action, waiting) ?? Promise.resolve(),
+    };
+}

package/dist/commands/advertised.d.ts

@@ -0,0 +1,23 @@
+import type { SessionExtensionSlots } from "@fungi.computer/shiitake/client";
+import type { WhistleRuntime } from "@fungi.computer/whistle";
+import type { ParakeetSession } from "../session.js";
+/** Why one advertised catalog could not become commands. */
+export type AdvertisedCatalogError = Readonly<{
+    /** The extension that advertised it. */
+    extensionId: string;
+    /** What was wrong. */
+    message: string;
+}>;
+/** Live commands for every catalog a Session's extensions advertise. */
+export type AdvertisedCommands = Readonly<{
+    /** Apply the latest extension slots; changed catalogs replace their commands. */
+    update: (slots: SessionExtensionSlots) => readonly AdvertisedCatalogError[];
+    /** Withdraw every advertised command. */
+    dispose: () => void;
+}>;
+/**
+ * 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.
+ */
+export declare function advertisedCommands(runtime: Pick<WhistleRuntime, "contribute">, session: Pick<ParakeetSession, "extension">, onInspect?: (entryId: string, commandId: string) => void): AdvertisedCommands;