@jini-ai/chat 0.5.4 → 0.5.6

package/dist/react/features/chat-pane/hooks/useAgentRuntimePicker.hooks.js

@@ -1,3 +1,4 @@
+import { pickerModelLabel } from '../model-options.js';
 /**
  * All of `AgentRuntimePicker`'s behavior, so the component itself is only markup.
  *
@@ -146,12 +147,12 @@ export function useAgentRuntimePicker({ agents, value, placement, t, executionMo
     const [position, setPosition] = useState();
     const triggerRef = useRef(null);
     const popoverRef = useRef(null);
-    const orderedAgents = useMemo(() => orderChatPaneAgents({ agents: agents.filter((agent) => agent.available !== false) }), [agents]);
+    const orderedAgents = useMemo(() => orderChatPaneAgents({ agents: agents.filter((agent) => agent.available !== false && agent.id !== 'gemini') }), [agents]);
     const selectedAgent = orderedAgents.find((agent) => agent.id === value.agentId);
     // `selectedAgent` stays resolved in BOTH modes on purpose — the CLI selection is still the stored
     // one, and switching back to Local CLI must not have silently lost it. What changes in `'api'` is
     // only what gets DESCRIBED, because none of the CLI's labels are true of an API turn.
-    const localModelLabel = runtimeOptionLabel({ options: selectedAgent?.models, value: value.model, fallback: t('Default model') });
+    const localModelLabel = pickerModelLabel(selectedAgent, value.model, t);
     const byok = byokSummaryText({ byokRuntime: byokRuntime, t: t });
     const isApi = executionMode === 'api';
     const modelLabel = isApi ? byok.modelLabel : localModelLabel;

package/dist/react/features/chat-pane/hooks/useChatPane.hooks.d.ts

@@ -1,3 +1,4 @@
+import type { UserTextRedactionOptions } from '../../../../core/user-text-redaction.js';
 import { type ChatPaneSendBlocker } from '../rules.js';
 import type { ChatPaneActivity, ChatPaneAgent, ChatPaneAttachmentUploadOptions, ChatPaneAgentSelection, ChatPaneRunContext, ChatPaneWorkingDirectoryAccess, DeliverTypedAnswer, TypedAnswerNotice } from '../types.js';
 import type { ChatAttachment, ChatMessage } from '@jini-ai/chat';
@@ -6,7 +7,7 @@ import type { ChatTransport } from '@jini-ai/chat';
 import { type UseComposerResult } from '../../../hooks/useComposer.js';
 import { type UseConversationResult } from '../../../hooks/useConversation.js';
 import { type UseChatPaneWorkingDirectoryResult } from './useChatPaneWorkingDirectory.hooks.js';
-export interface UseChatPaneOptions {
+export interface UseChatPaneOptions extends UserTextRedactionOptions {
     transport: ChatTransport;
     agents: readonly ChatPaneAgent[];
     initialMessages?: ChatMessage[];
@@ -37,6 +38,8 @@ export interface UseChatPaneOptions {
     deliverTypedAnswer?: DeliverTypedAnswer;
 }
 export interface UseChatPaneResult extends UseChatPaneWorkingDirectoryResult {
+    /** Show a localized non-secret notice when a paste was removed. */
+    secretRedacted: boolean;
     conversation: UseConversationResult;
     composer: UseComposerResult;
     selection: ChatPaneAgentSelection;

package/dist/react/features/chat-pane/hooks/useChatPane.hooks.js

@@ -1,3 +1,4 @@
+import { useUserTextGuard } from '../../../hooks/useUserTextGuard.js';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { describeChatPaneSendBlocker, findAwaitedTypedAnswerId, findChatPaneSendBlocker, isChatPaneQueueableBlocker, isTypedAnswerTurn, resolveChatPaneSelection, } from '../rules.js';
 import { definedProps } from '../../../util/defined-props.js';
@@ -73,9 +74,11 @@ async function uploadAttachmentBatch(files, effects) {
     }
 }
 export function useChatPane(options) {
+    const guard = useUserTextGuard(options);
     const [activeUploadCount, setActiveUploadCount] = useState(0);
     const [attachmentError, setAttachmentError] = useState(null);
-    const [queuedPrompt, setQueuedPrompt] = useState(null);
+    // Keep the signal with sanitized queue text; re-redacting it later cannot detect the original paste.
+    const [queuedTurn, setQueuedTurn] = useState(null);
     const [typedAnswerNotice, setTypedAnswerNotice] = useState(null);
     // Set across the await of one typed-answer delivery so a second Enter cannot post the same text
     // twice — the second post would find the question already answered and wrongly report it closed.
@@ -112,10 +115,19 @@ export function useChatPane(options) {
             workingDirectoryAccess: options.workingDirectoryAccess,
         } }));
     const requestedSelection = options.selection ?? internalSelection;
-    const selection = useMemo(() => resolveChatPaneSelection({ agents: options.agents, requested: requestedSelection }), [options.agents, requestedSelection]);
+    const resolvedSelection = useMemo(() => resolveChatPaneSelection({ agents: options.agents, requested: requestedSelection }), [options.agents, requestedSelection]);
+    // Inline inventories and controlled selections can be new objects on every render. Keep the
+    // normalized value stable so synchronizing it into composer state cannot feed a render loop.
+    const selection = useMemo(() => definedProps({ source: {
+            agentId: resolvedSelection.agentId,
+            model: resolvedSelection.model,
+            reasoning: resolvedSelection.reasoning,
+        } }), [resolvedSelection.agentId, resolvedSelection.model, resolvedSelection.reasoning]);
     const selectedAgent = options.agents.find((agent) => agent.id === selection.agentId);
     const conversation = useConversation(definedProps({ source: {
             transport: options.transport,
+            redactUserText: options.redactUserText,
+            onSecretRedacted: guard.notifyRedaction,
             initialMessages: options.initialMessages,
             conversationId: options.conversationId,
             // Keys off an empty string, not `undefined` — `selection.agentId` is always a string (never
@@ -148,6 +160,8 @@ export function useChatPane(options) {
             activeUploadsRef.current.clear();
         };
     }, []);
+    const selectionControlled = options.selection !== undefined;
+    const setComposerAgent = composer.setAgent;
     useEffect(() => {
         if (!selection.agentId)
             return;
@@ -155,14 +169,14 @@ export function useChatPane(options) {
             && requestedSelection.model === selection.model
             && requestedSelection.reasoning === selection.reasoning)
             return;
-        if (options.selection === undefined)
+        if (!selectionControlled)
             setInternalSelection(selection);
-        composer.setAgent(selection);
+        setComposerAgent(selection);
         options.onSelectionChange?.(selection);
     }, [
-        composer,
+        setComposerAgent,
         options.onSelectionChange,
-        options.selection,
+        selectionControlled,
         requestedSelection.agentId,
         requestedSelection.model,
         requestedSelection.reasoning,
@@ -175,6 +189,7 @@ export function useChatPane(options) {
         options.onSelectionChange?.(validated);
     }, [composer, options.agents, options.onSelectionChange]);
     const sendBlocker = findChatPaneSendBlocker({
+        ...(selection.model ? { model: selection.model } : {}),
         selectedAgent,
         isStreaming: conversation.isStreaming,
         activeUploadCount,
@@ -267,8 +282,8 @@ export function useChatPane(options) {
             }
         }
     }, [composer, options.conversationId, options.uploadAttachments]);
-    const sendPrompt = useCallback(async (prompt) => {
-        const trimmed = prompt.trim();
+    const sendGuardedPrompt = useCallback(async ({ redaction }, _optional = {}) => {
+        const trimmed = redaction.text.trim();
         if (!trimmed)
             throw new Error('cannot send: the prompt is empty');
         if (sendBlocker !== null) {
@@ -287,6 +302,7 @@ export function useChatPane(options) {
         attachmentBatchIdRef.current = createAttachmentBatchId();
         options.onActivityChange?.('queued');
         await conversation.sendMessage(trimmed, definedProps({ source: {
+                secretRedaction: redaction.secretRedacted ? { secretRedacted: true, count: redaction.count } : undefined,
                 agentId: selection.agentId,
                 // Omitted when the array is EMPTY, not merely absent — an empty `attachments: []` would be a
                 // different (valid, present) value to the transport than "no attachments key at all".
@@ -302,12 +318,16 @@ export function useChatPane(options) {
         sendBlocker,
         workingDirectoryState.workingDirectory,
     ]);
+    const sendPrompt = useCallback(async (prompt) => {
+        await sendGuardedPrompt({ redaction: guard.redact({ text: prompt.trim() }, {}) }, {});
+    }, [guard.redact, sendGuardedPrompt]);
     const answerWaitingQuestion = useCallback(async ({ deliver, text }) => {
+        const safeText = guard.redactText(text);
         const generation = typedAnswerGenerationRef.current;
         const submittedDraft = latestDraftRef.current;
         const questionId = awaitedQuestionId;
         deliveringTypedAnswerRef.current = true;
-        const outcome = await deliverTypedAnswerSafely({ deliver, text });
+        const outcome = await deliverTypedAnswerSafely({ deliver, text: safeText });
         deliveringTypedAnswerRef.current = false;
         if (!mountedRef.current || generation !== typedAnswerGenerationRef.current)
             return;
@@ -323,21 +343,21 @@ export function useChatPane(options) {
         // correction or next message typed while the host answered.
         if (latestDraftRef.current === submittedDraft)
             composer.setDraft('');
-    }, [awaitedQuestionId, composer]);
+    }, [awaitedQuestionId, composer, guard.redactText]);
     // The ordinary next-turn path: queue behind a running run, else send now.
     const sendOrdinaryTurn = useCallback(async (prompt) => {
         // Queue instead of no-op'ing. `setDraft('')` and NOT `composer.reset()`: reset also discards
         // staged attachments, which this turn still needs when it finally goes out.
         if (isChatPaneQueueableBlocker({ blocker: sendBlocker })) {
             queuedConversationIdRef.current = options.conversationId;
-            setQueuedPrompt(prompt);
+            setQueuedTurn(guard.redact({ text: prompt }, {}));
             composer.setDraft('');
             return;
         }
         if (!canSend)
             return;
         await sendPrompt(prompt);
-    }, [canSend, composer, options.conversationId, sendBlocker, sendPrompt]);
+    }, [canSend, composer, options.conversationId, sendBlocker, sendPrompt, guard.redact]);
     const send = useCallback(async () => {
         const prompt = composerPrompt(composer);
         if (!prompt || deliveringTypedAnswerRef.current)
@@ -385,31 +405,31 @@ export function useChatPane(options) {
         if (!prompt)
             return;
         queuedConversationIdRef.current = options.conversationId;
-        setQueuedPrompt(prompt);
+        setQueuedTurn(guard.redact({ text: prompt }, {}));
         composer.setDraft('');
         conversation.cancel();
-    }, [composer, conversation, options.conversationId]);
+    }, [composer, conversation, options.conversationId, guard.redact]);
     const cancelQueued = useCallback(() => {
         queuedConversationIdRef.current = undefined;
-        setQueuedPrompt(null);
+        setQueuedTurn(null);
     }, []);
     // Flush on a FULLY clear blocker, not merely on streaming ending — see
     // `isChatPaneQueueableBlocker`'s note about `findChatPaneSendBlocker`'s ordering. Clearing the
     // queue slot BEFORE awaiting keeps a re-render from double-sending the same prompt.
     useEffect(() => {
-        if (queuedPrompt === null || sendBlocker !== null)
+        if (queuedTurn === null || sendBlocker !== null)
             return;
         if (queuedConversationIdRef.current !== options.conversationId) {
             // The conversation changed while this prompt waited behind a streaming run — sending it now
             // would post it into a conversation the user never saw it queued against. Drop it instead
             // (same as `cancelQueued`) rather than misrouting it.
             queuedConversationIdRef.current = undefined;
-            setQueuedPrompt(null);
+            setQueuedTurn(null);
             return;
         }
-        setQueuedPrompt(null);
-        void sendPrompt(queuedPrompt);
-    }, [options.conversationId, queuedPrompt, sendBlocker, sendPrompt]);
+        setQueuedTurn(null);
+        void sendGuardedPrompt({ redaction: queuedTurn }, {});
+    }, [options.conversationId, queuedTurn, sendBlocker, sendGuardedPrompt]);
     const reset = useCallback(() => {
         attachmentGenerationRef.current += 1;
         attachmentBatchIdRef.current = createAttachmentBatchId();
@@ -428,9 +448,10 @@ export function useChatPane(options) {
         // `conversation.cancel()` above clears the streaming blocker — the flush effect fires it into
         // the just-reset conversation instead of discarding it like the rest of this turn's state.
         queuedConversationIdRef.current = undefined;
-        setQueuedPrompt(null);
+        setQueuedTurn(null);
     }, [composer, conversation, options.initialMessages]);
     return {
+        secretRedacted: guard.secretRedacted,
         conversation,
         composer,
         selection,
@@ -446,7 +467,7 @@ export function useChatPane(options) {
         addAttachments,
         send,
         sendPrompt,
-        queuedPrompt,
+        queuedPrompt: queuedTurn?.text ?? null,
         cancelQueued,
         typedAnswerNotice,
         sendAsNewMessage,

package/dist/react/features/chat-pane/model-options.d.ts

@@ -0,0 +1,12 @@
+import type { I18nAdapter } from '../../slots.js';
+import type { ChatPaneAgent, ChatPaneAgentOption } from './types.js';
+export declare function isConcretePickerModel(id: string): boolean;
+/** Aliases are selectable only as their evidence-backed concrete ID. Never render a Default row.
+ * @complexity O(n) time and space in catalog rows, with set-based deduplication.
+ */
+export declare function pickerModelOptions(agent: ChatPaneAgent): ChatPaneAgentOption[];
+export declare function configuredPickerModel(agent: ChatPaneAgent): string | undefined;
+export declare function pickerModelLabel(agent: ChatPaneAgent | undefined, requested?: string, t?: I18nAdapter['t']): string;
+export declare function pickerModelValue(agent: ChatPaneAgent, requested?: string): string;
+export declare function pickerCatalogNote(agent: ChatPaneAgent, t?: I18nAdapter['t']): string | undefined;
+//# sourceMappingURL=model-options.d.ts.map

package/dist/react/features/chat-pane/model-options.js

@@ -0,0 +1,55 @@
+// Model names and timestamps are metadata; only surrounding picker copy is translated.
+const passthrough = key => key;
+export function isConcretePickerModel(id) {
+    const token = id.slice(id.lastIndexOf('/') + 1);
+    return !/^(?:opus|sonnet|haiku|fable|best|latest|claude|gemini|gpt|codex|swe)(?:\[.*\])?$/i.test(token) && !/^(default|auto|adaptive|smart|deep|rush|ultimate|premium|balanced|fast|grok-build|vercel-ai-gateway)$/i.test(token) && !/(?:^|[-/])(gateway|latest)$/i.test(id);
+}
+/** Aliases are selectable only as their evidence-backed concrete ID. Never render a Default row.
+ * @complexity O(n) time and space in catalog rows, with set-based deduplication.
+ */
+export function pickerModelOptions(agent) {
+    if (agent.supportsConcreteModelSelection === false)
+        return [];
+    const seen = new Set();
+    const options = (agent.models || []).flatMap((row) => {
+        const id = row.resolvedId || (row.identityKind === 'routing-mode' || row.identityKind === 'alias' ? undefined : row.id);
+        if (!id || !isConcretePickerModel(id) || seen.has(id))
+            return [];
+        seen.add(id);
+        // Older cached inventories can attach a default-policy label to a resolved concrete ID.
+        const label = row.id === 'default' || /^default\b/i.test(row.label) ? id : row.label;
+        return [{ ...row, id, label, identityKind: 'concrete' }];
+    });
+    const resolution = agent.defaultModelResolution;
+    // A host may publish a resolved default outside its visible catalog. Preserve its concrete ID.
+    if (resolution?.status === 'resolved' && isConcretePickerModel(resolution.id) && !seen.has(resolution.id))
+        options.unshift({ id: resolution.id, label: resolution.id, identityKind: 'concrete' });
+    return options;
+}
+export function configuredPickerModel(agent) {
+    if (agent.supportsConcreteModelSelection === false)
+        return undefined;
+    const resolution = agent.defaultModelResolution;
+    return resolution?.status === 'resolved' && isConcretePickerModel(resolution.id) ? resolution.id : undefined;
+}
+export function pickerModelLabel(agent, requested, t = passthrough) {
+    if (!agent)
+        return t('Choose model');
+    const id = !requested || requested === 'default' ? configuredPickerModel(agent) : requested;
+    if (!id || !isConcretePickerModel(id))
+        return t('Choose model');
+    return pickerModelOptions(agent).find((row) => row.id === id)?.label || id;
+}
+export function pickerModelValue(agent, requested) {
+    const id = requested && requested !== 'default' ? requested : configuredPickerModel(agent);
+    return id && pickerModelOptions(agent).some((row) => row.id === id) ? id : '';
+}
+export function pickerCatalogNote(agent, t = passthrough) {
+    const catalog = agent.modelCatalog;
+    if (catalog?.freshness === 'stale')
+        return `${t('Cached')} · ${catalog.fetchedAt}`;
+    if (catalog?.freshness === 'offline-fallback' || !catalog && agent.models)
+        return t('Offline fallback');
+    return undefined;
+}
+//# sourceMappingURL=model-options.js.map

package/dist/react/features/chat-pane/rules.d.ts

@@ -14,9 +14,10 @@ export declare function resolveChatPaneSelection({ agents, requested }: {
  * precondition (`composer.canSubmit`), not a property of the pane. An agent-driven send supplies
  * its own prompt and must still clear every blocker below.
  */
-export type ChatPaneSendBlocker = 'no-agent-selected' | 'agent-unavailable' | 'streaming' | 'uploads-pending' | 'working-directory-pending' | 'working-directory-invalid' | 'working-directory-error';
+export type ChatPaneSendBlocker = 'no-agent-selected' | 'agent-unavailable' | 'model-unresolved' | 'streaming' | 'uploads-pending' | 'working-directory-pending' | 'working-directory-invalid' | 'working-directory-error';
 export interface ChatPaneSendability {
-    readonly selectedAgent: Pick<ChatPaneAgent, 'available'> | undefined;
+    readonly selectedAgent: Pick<ChatPaneAgent, 'available' | 'modelCatalog' | 'supportsConcreteModelSelection'> | undefined;
+    readonly model?: string;
     readonly isStreaming: boolean;
     readonly activeUploadCount: number;
     readonly workingDirectoryPending: boolean;

package/dist/react/features/chat-pane/rules.js

@@ -1,3 +1,4 @@
+import { configuredPickerModel, pickerModelOptions, isConcretePickerModel } from './model-options.js';
 function preferredOptionId(options) {
     return options?.find((option) => option.id === 'default')?.id ?? options?.[0]?.id;
 }
@@ -7,7 +8,9 @@ function validatedOptionId(options, requested, fallback) {
     return fallback;
 }
 export function defaultChatPaneSelection({ agent }) {
-    const model = preferredOptionId(agent.models);
+    // An unresolved native route requires an intentional concrete choice. Legacy hosts without
+    // structured resolution retain their first-concrete-entry behavior.
+    const model = configuredPickerModel(agent) || (agent.defaultModelResolution?.status === 'unresolved' ? undefined : pickerModelOptions(agent)[0]?.id);
     const reasoning = preferredOptionId(agent.reasoningOptions);
     return {
         agentId: agent.id,
@@ -16,17 +19,19 @@ export function defaultChatPaneSelection({ agent }) {
     };
 }
 export function resolveChatPaneSelection({ agents, requested }) {
-    const requestedAgent = agents.find((agent) => agent.id === requested.agentId && agent.available !== false);
-    const agent = requestedAgent ?? agents.find((candidate) => candidate.available !== false);
+    const requestedAgent = agents.find((agent) => agent.id === requested.agentId && agent.id !== 'gemini' && agent.available !== false);
+    const agent = requestedAgent ?? agents.find((candidate) => candidate.id !== 'gemini' && candidate.available !== false);
     if (!agent)
         return { agentId: '' };
     const defaults = defaultChatPaneSelection({ agent: agent });
     if (agent !== requestedAgent)
         return defaults;
     const model = requested.model
+        && isConcretePickerModel(requested.model)
         && agent.supportsCustomModel
+        && agent.supportsConcreteModelSelection !== false
         ? requested.model
-        : validatedOptionId(agent.models, requested.model, defaults.model);
+        : validatedOptionId(pickerModelOptions(agent), requested.model, defaults.model);
     const reasoning = validatedOptionId(agent.reasoningOptions, requested.reasoning, defaults.reasoning);
     return {
         agentId: agent.id,
@@ -64,6 +69,8 @@ export function findChatPaneSendBlocker(state) {
     else if (state.selectedAgent.available === false) {
         return 'agent-unavailable';
     }
+    if (!state.apiModeConfigured && state.selectedAgent && (state.selectedAgent.modelCatalog || state.selectedAgent.supportsConcreteModelSelection === false) && (!state.model || !isConcretePickerModel(state.model) || state.selectedAgent.supportsConcreteModelSelection === false))
+        return 'model-unresolved';
     if (state.isStreaming)
         return 'streaming';
     if (state.activeUploadCount > 0)
@@ -79,6 +86,7 @@ export function findChatPaneSendBlocker(state) {
 const SEND_BLOCKER_MESSAGES = {
     'no-agent-selected': 'no agent is selected',
     'agent-unavailable': 'the selected agent is unavailable',
+    'model-unresolved': 'choose a concrete model before sending',
     streaming: 'a run is already streaming — cancel it first',
     'uploads-pending': 'attachment uploads are still in flight',
     'working-directory-pending': 'the working directory is still being validated',

package/dist/react/features/chat-pane/types.d.ts

@@ -1,3 +1,4 @@
+import type { UserTextRedactionOptions } from '../../../core/user-text-redaction.js';
 import type { CSSProperties, ReactNode, RefObject } from 'react';
 import type { ChatAttachment, ChatMessage } from '@jini-ai/chat';
 import type { ComposerSlots } from '../../slots.js';
@@ -6,6 +7,8 @@ import type { ChatTransport, RunContext } from '@jini-ai/chat';
 export interface ChatPaneAgentOption {
     id: string;
     label: string;
+    identityKind?: 'concrete' | 'alias' | 'routing-mode';
+    resolvedId?: string;
 }
 /**
  * Browser-safe runtime inventory consumed by the chat pane. This is
@@ -19,8 +22,29 @@ export interface ChatPaneAgent {
     version?: string | null;
     authStatus?: 'ok' | 'missing' | 'unknown';
     models?: readonly ChatPaneAgentOption[];
+    modelCatalog?: {
+        source: 'cli' | 'rpc' | 'provider-api' | 'cli-cache' | 'config-file' | 'offline-fallback';
+        freshness: 'fresh' | 'stale' | 'offline-fallback';
+        fetchedAt: string;
+        expiresAt: string;
+        coverage: 'account' | 'provider' | 'configured' | 'observed';
+        launchFingerprint: string;
+    };
+    defaultModelResolution?: {
+        status: 'resolved';
+        id: string;
+        selectionId?: string;
+        source: string;
+        resolvedAt: string;
+        launchFingerprint: string;
+    } | {
+        status: 'unresolved';
+        selectionId?: string;
+        reason: string;
+    };
     reasoningOptions?: readonly ChatPaneAgentOption[];
     supportsCustomModel?: boolean;
+    supportsConcreteModelSelection?: boolean;
     diagnostic?: string;
     /**
      * Whether this runtime can receive external MCP servers (host/Jini tools) at all — mirrors
@@ -143,7 +167,7 @@ export type DeliverTypedAnswer = ((input: {
 }) => Promise<TypedAnswerDelivery>) & {
     readonly toolName: string;
 };
-export interface ChatPaneProps {
+export interface ChatPaneProps extends UserTextRedactionOptions {
     transport: ChatTransport;
     agents?: readonly ChatPaneAgent[];
     /** Optional host effects for package-owned inventory, rescan, and health polling. */

package/dist/react/hooks/assistant-chats-contracts.d.ts

@@ -0,0 +1,164 @@
+import type { ChatMessage } from "../../core/messages.js";
+import type { AssistantConversation } from "../../core/assistant-client/messages.js";
+/**
+ * @file What `useAssistantChats` needs from the outside world, as an interface rather than a set of
+ * module imports.
+ *
+ * The hook used to import `lib/assistant-chats`'s functions directly, which meant the only way to
+ * test it was to stub the global `fetch` and assert on the URLs and methods that came out — the
+ * tests described HTTP when what they meant to describe was "which conversation did this message
+ * get written to". Worse, behaviour that has nothing to do with transport (the write retry and its
+ * backoff) could only be exercised by hand-building `Response` objects with the right status codes.
+ *
+ * Declaring the seam here follows the `useX(dependencies)` / `useWiredX()` pair this workspace
+ * already uses throughout `@jini-ai/ui` (see `features/html-viewer/react/hooks/usePresentMode.ts`
+ * for the canonical shape, and `foundry/docs/jini-port/skills/fixing-open-design-web.md` for the
+ * rules). `ports.ts` declares, `assistant-chats-dependencies.ts` binds, and nothing else imports the
+ * real provider.
+ *
+ * `AssistantConversation` is imported here `import type`, which is erased at compile time — so this
+ * file still has no runtime dependency on `lib/assistant-chats`, and `dependencies.ts` remains the
+ * single place the real implementation is reached.
+ *
+ * ## What is deliberately NOT in this port
+ *
+ * `persistableMessages` and `HttpError`. The first is a pure rule — no I/O, no host — and per the
+ * pattern a hook imports rules directly rather than having them injected; making it swappable would
+ * let a fake quietly change which messages count as settled, which is the one thing every test here
+ * needs to hold still. The second is the error type an implementation is expected to throw for a
+ * non-2xx response, and it is part of this contract even though it is not a method: {@link
+ * AssistantChatsPort.saveMessage}'s retry classifies failures by it.
+ */
+export interface AssistantChatsPort {
+    listConversations(required: Record<string, never>, optional: Record<string, never>): Promise<AssistantConversation[]>;
+    /** `firstMessage` seeds the server-side title heuristic; omit it for an untitled empty chat. */
+    createConversation(required: {
+        firstMessage?: string;
+    }, optional: Record<string, never>): Promise<AssistantConversation>;
+    renameConversation(required: {
+        id: string;
+        title: string;
+    }, optional: Record<string, never>): Promise<void>;
+    deleteConversation(required: {
+        id: string;
+    }, optional: Record<string, never>): Promise<void>;
+    loadMessages(required: {
+        conversationId: string;
+    }, optional: Record<string, never>): Promise<ChatMessage[]>;
+    /**
+     * Writes one message.
+     *
+     * Expected to reject with an `HttpError` for a non-2xx response and with anything else for a
+     * transport failure — the hook retries the second kind, and the first only for 429/5xx. An
+     * implementation that swallows failures into a resolved promise silently disables the retry.
+     */
+    saveMessage(required: {
+        conversationId: string;
+        message: ChatMessage;
+    }, optional: Record<string, never>): Promise<void>;
+}
+export interface UseAssistantChats {
+    conversations: AssistantConversation[];
+    activeId: string | null;
+    /**
+     * `ChatPane`'s `key`. Deliberately NOT `activeId`.
+     *
+     * Remounting the pane is correct for a user-initiated switch and destructive at any other time: it
+     * re-seeds from `initialMessages` and discards whatever the pane currently holds. `activeId` now
+     * also changes when an untitled pane silently adopts a freshly created conversation mid-run (see
+     * `onMessagesChange`), and re-keying on that would wipe the reply being streamed. So the two are
+     * separate: this changes only on `select`/`create`/`remove`, `activeId` tracks where writes go.
+     */
+    paneKey: string;
+    /** Messages to seed the pane with. Changes identity only on a real conversation switch. */
+    initialMessages: ChatMessage[];
+    select: (required: {
+        id: string;
+    }, optional?: Record<string, never>) => void;
+    create: (required: Record<string, never>, optional?: Record<string, never>) => Promise<void>;
+    remove: (required: {
+        id: string;
+    }, optional?: Record<string, never>) => Promise<void>;
+    rename: (required: {
+        id: string;
+        title: string;
+    }, optional?: Record<string, never>) => Promise<void>;
+    onMessagesChange: (required: {
+        messages: ChatMessage[];
+    }, optional?: Record<string, never>) => void;
+    /**
+     * This pane's conversation id, adopting one if none is active yet. Awaited by
+     * `assistant-transport.ts`'s `startRun` so turn 1's run carries the identity its agent-CLI session
+     * id gets filed under — see the hook's own implementation doc for the amnesia defect that needs it.
+     * Resolves `null` (never rejects) when creation fails.
+     */
+    ensureConversationId: (required: Record<string, never>, optional?: Record<string, never>) => Promise<string | null>;
+    /**
+     * Writes one user turn durably, awaited by `assistant-transport.ts`'s `startRun` BEFORE it
+     * dispatches the run — see the implementation's own doc for the defect (a failed run's user
+     * message reaching no agent and no later prompt). Never rejects; a failed write releases the id
+     * so the delta-driven `flush` can still pick it up.
+     */
+    persistUserTurn: (required: {
+        conversationId: string;
+        message: ChatMessage;
+    }, optional?: Record<string, never>) => Promise<void>;
+}
+export interface AssistantChatsClientPorts {
+    readonly statusOf: (required: {
+        error: unknown;
+    }, optional: Record<string, never>) => number | undefined;
+    readonly sleep: (required: {
+        delayMs: number;
+    }, optional: Record<string, never>) => Promise<void>;
+    readonly reportPermanent: (required: {
+        conversationId: string;
+        messageId: string;
+        error: unknown;
+    }, optional: Record<string, never>) => void;
+    readonly requestRunPrefixes: readonly string[];
+}
+export type SaveOutcome = "saved" | "exhausted" | "permanent" | "missing";
+export type AttemptResult = {
+    done: true;
+    outcome: SaveOutcome;
+} | {
+    done: false;
+};
+export interface SaveFailureInput {
+    error: unknown;
+    conversationId: string;
+    message: ChatMessage;
+    attempt: number;
+    isDisposed: () => boolean;
+}
+export interface AssistantChatsClient {
+    giveUpOutcome(required: {
+        error: unknown;
+    }, optional?: Record<string, never>): SaveOutcome;
+    handleSaveFailure(required: SaveFailureInput, optional?: Record<string, never>): Promise<AttemptResult>;
+    attemptSave(required: Omit<SaveFailureInput, "error"> & {
+        port: AssistantChatsPort;
+    }, optional?: Record<string, never>): Promise<AttemptResult>;
+    summarizeFlushOutcomes(required: {
+        results: readonly {
+            message: ChatMessage;
+            outcome: SaveOutcome;
+        }[];
+        isConversationStillActive: boolean;
+    }, optional?: Record<string, never>): {
+        idsToRelease: string[];
+        shouldRefresh: boolean;
+    };
+    resolveRememberedConversation(required: {
+        remembered: string | null;
+        conversations: readonly AssistantConversation[];
+        listFailed: boolean;
+    }, optional?: Record<string, never>): "restore" | "forget" | "keep";
+    useAssistantChats(required: {
+        port: AssistantChatsPort;
+    }, optional?: {
+        lastConversation?: import("./last-conversation-store.js").LastConversationStore;
+    }): UseAssistantChats;
+}
+//# sourceMappingURL=assistant-chats-contracts.d.ts.map

package/dist/react/hooks/assistant-chats-contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=assistant-chats-contracts.js.map

package/dist/react/hooks/assistant-chats.d.ts

@@ -0,0 +1,7 @@
+import type { AssistantChatsClientPorts, AssistantChatsClient } from "./assistant-chats-contracts.js";
+/** Bind effects once; the returned hook captures its conversation port at mount.
+ * Existing race guards and retry ordering remain in the original lexical lifecycle. */
+export declare function createAssistantChatsClient({ ports }: {
+    ports: AssistantChatsClientPorts;
+}, _options?: Record<string, never>): AssistantChatsClient;
+//# sourceMappingURL=assistant-chats.d.ts.map