@jini-ai/chat 0.5.0 → 0.5.2

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

@@ -1,4 +1,5 @@
-import type { ByokRuntimeSummary, ChatPaneAgent, ChatPaneAgentSelection } from './types.js';
+import type { ChatMessage } from '@jini-ai/chat';
+import type { ByokRuntimeSummary, ChatPaneAgent, ChatPaneAgentSelection, TypedAnswerNotice } from './types.js';
 export declare function defaultChatPaneSelection({ agent }: {
     agent: ChatPaneAgent;
 }): ChatPaneAgentSelection;
@@ -71,6 +72,60 @@ export declare function describeChatPaneSendBlocker(blocker: ChatPaneSendBlocker
 export declare function isChatPaneQueueableBlocker({ blocker }: {
     blocker: ChatPaneSendBlocker | null;
 }): boolean;
+/**
+ * Whether the run in flight is holding a question open for the human: the newest message is the
+ * assistant's, and it carries an interactive surface (`kind: 'ext'`, e.g. an MCP-UI card) that
+ * arrived inside a still-open call to the host's question tool (`toolName`). That is the one moment
+ * text typed into the composer is an ANSWER rather than a next turn — the tool is parked waiting on
+ * it, and queueing the text behind the run would only deliver it after the question had expired, as
+ * a new paid run.
+ *
+ * Only the question tool counts. Other tools park on cards too — a delete confirm, an approval —
+ * but they take no typed answer: the server routes typed text only to the question tool, so treating
+ * those as waiting would refuse the text with "no longer waiting" and drop it instead of queueing.
+ * A call is the question tool when ANY `tool_use` for its id names it, since a vendor's wrapper row
+ * (`execute_delegated_tool`) and the daemon's canonical row share the id and may arrive in either
+ * order.
+ *
+ * A surface is attributed to the newest call still open when it arrived — the same rule
+ * `useExtEventGroups` uses to give a card its `call` — so an older call returning does not settle
+ * it. Once its call returns (answered, expired, abandoned), typing is a next turn again.
+ *
+ * @complexity O(e·c): e events in the newest message, c calls open at once (one or two in practice).
+ */
+export declare function isAwaitingTypedAnswer({ messages, toolName }: {
+    messages: readonly ChatMessage[];
+    toolName: string;
+}): boolean;
+/**
+ * The tool-use id of the question {@link isAwaitingTypedAnswer} sees waiting, or `null` — the newest
+ * one when several are open. The id lets the pane tell one question from the next: a draft typed
+ * for a question stays tied to THAT question after it closes (see `useChatPane`'s held answer).
+ *
+ * @complexity O(e·c), as {@link isAwaitingTypedAnswer}.
+ */
+export declare function findAwaitedTypedAnswerId({ messages, toolName }: {
+    messages: readonly ChatMessage[];
+    toolName: string;
+}): string | null;
+/**
+ * Whether a composer send is an answer to a waiting question rather than a next turn: a run is
+ * streaming ({@link isChatPaneQueueableBlocker}), the turn has no attachments (a typed answer
+ * carries text only), and that run is holding the `toolName` question open
+ * ({@link isAwaitingTypedAnswer}).
+ *
+ * @complexity O(e·c), from {@link isAwaitingTypedAnswer}.
+ */
+export declare function isTypedAnswerTurn({ blocker, attachmentCount, messages, toolName }: {
+    blocker: ChatPaneSendBlocker | null;
+    attachmentCount: number;
+    messages: readonly ChatMessage[];
+    toolName: string;
+}): boolean;
+/** The English copy (and i18n key) for why a typed answer was not sent. */
+export declare function describeTypedAnswerNotice({ notice }: {
+    notice: TypedAnswerNotice;
+}): string;
 export declare function orderChatPaneAgents({ agents }: {
     agents: readonly ChatPaneAgent[];
 }): ChatPaneAgent[];

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

@@ -105,6 +105,77 @@ export function describeChatPaneSendBlocker(blocker) {
 export function isChatPaneQueueableBlocker({ blocker }) {
     return blocker === 'streaming';
 }
+/**
+ * Whether the run in flight is holding a question open for the human: the newest message is the
+ * assistant's, and it carries an interactive surface (`kind: 'ext'`, e.g. an MCP-UI card) that
+ * arrived inside a still-open call to the host's question tool (`toolName`). That is the one moment
+ * text typed into the composer is an ANSWER rather than a next turn — the tool is parked waiting on
+ * it, and queueing the text behind the run would only deliver it after the question had expired, as
+ * a new paid run.
+ *
+ * Only the question tool counts. Other tools park on cards too — a delete confirm, an approval —
+ * but they take no typed answer: the server routes typed text only to the question tool, so treating
+ * those as waiting would refuse the text with "no longer waiting" and drop it instead of queueing.
+ * A call is the question tool when ANY `tool_use` for its id names it, since a vendor's wrapper row
+ * (`execute_delegated_tool`) and the daemon's canonical row share the id and may arrive in either
+ * order.
+ *
+ * A surface is attributed to the newest call still open when it arrived — the same rule
+ * `useExtEventGroups` uses to give a card its `call` — so an older call returning does not settle
+ * it. Once its call returns (answered, expired, abandoned), typing is a next turn again.
+ *
+ * @complexity O(e·c): e events in the newest message, c calls open at once (one or two in practice).
+ */
+export function isAwaitingTypedAnswer({ messages, toolName }) {
+    return findAwaitedTypedAnswerId({ messages, toolName }) !== null;
+}
+/**
+ * The tool-use id of the question {@link isAwaitingTypedAnswer} sees waiting, or `null` — the newest
+ * one when several are open. The id lets the pane tell one question from the next: a draft typed
+ * for a question stays tied to THAT question after it closes (see `useChatPane`'s held answer).
+ *
+ * @complexity O(e·c), as {@link isAwaitingTypedAnswer}.
+ */
+export function findAwaitedTypedAnswerId({ messages, toolName }) {
+    const newest = messages.at(-1);
+    if (newest?.role !== 'assistant')
+        return null;
+    // Open call id -> whether it is the question tool. Insertion-ordered, so the last entry is the
+    // newest call still open; a repeat id keeps its slot and only ORs in its name.
+    const openCalls = new Map();
+    const awaited = new Set();
+    for (const event of newest.events ?? []) {
+        if (event.kind === 'tool_use')
+            openCalls.set(event.id, openCalls.get(event.id) === true || event.name === toolName);
+        if (event.kind === 'tool_result') {
+            openCalls.delete(event.toolUseId);
+            awaited.delete(event.toolUseId);
+        }
+        const owner = event.kind === 'ext' ? [...openCalls].at(-1) : undefined;
+        if (owner?.[1] === true)
+            awaited.add(owner[0]);
+    }
+    return [...awaited].at(-1) ?? null;
+}
+/**
+ * Whether a composer send is an answer to a waiting question rather than a next turn: a run is
+ * streaming ({@link isChatPaneQueueableBlocker}), the turn has no attachments (a typed answer
+ * carries text only), and that run is holding the `toolName` question open
+ * ({@link isAwaitingTypedAnswer}).
+ *
+ * @complexity O(e·c), from {@link isAwaitingTypedAnswer}.
+ */
+export function isTypedAnswerTurn({ blocker, attachmentCount, messages, toolName }) {
+    return isChatPaneQueueableBlocker({ blocker }) && attachmentCount === 0 && isAwaitingTypedAnswer({ messages, toolName });
+}
+const TYPED_ANSWER_NOTICES = {
+    'not-pending': 'That question is no longer waiting for an answer, so your message was not sent.',
+    failed: 'Your answer could not be delivered. Try sending it again.',
+};
+/** The English copy (and i18n key) for why a typed answer was not sent. */
+export function describeTypedAnswerNotice({ notice }) {
+    return TYPED_ANSWER_NOTICES[notice];
+}
 export function orderChatPaneAgents({ agents }) {
     return [...agents].sort((left, right) => {
         const availability = Number(left.available === false) - Number(right.available === false);

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

@@ -120,6 +120,28 @@ export interface ChatPaneComposerHandle {
      */
     insertText: (text: string) => void;
 }
+/**
+ * What happened to text typed while the running agent waits on a question (see
+ * {@link ChatPaneProps.deliverTypedAnswer}): `'delivered'` — the question took it as its answer;
+ * `'not-pending'` — nothing is waiting any more (already answered, expired, or never open);
+ * `'failed'` — the host could not tell (network error, unexpected status).
+ */
+export type TypedAnswerDelivery = 'delivered' | 'not-pending' | 'failed';
+/** Why the pane did not send a typed answer — shown to the human until the next send or reset. */
+export type TypedAnswerNotice = Exclude<TypedAnswerDelivery, 'delivered'>;
+/**
+ * Delivers text typed into the composer to the question the running agent is waiting on.
+ *
+ * Carries `toolName`, the host's question tool id, so the pane routes typed text here only while a
+ * card raised by THAT tool is open — any other pending card (a confirm, an approval) still queues the
+ * text behind the run. One value, so the tool the pane waits on and the tool the answer is posted to
+ * cannot drift apart; `createTypedAnswerPoster` sets it.
+ */
+export type DeliverTypedAnswer = ((input: {
+    text: string;
+}) => Promise<TypedAnswerDelivery>) & {
+    readonly toolName: string;
+};
 export interface ChatPaneProps {
     transport: ChatTransport;
     agents?: readonly ChatPaneAgent[];
@@ -170,6 +192,18 @@ export interface ChatPaneProps {
      * before the pane exists has nothing to call.
      */
     composerHandle?: RefObject<ChatPaneComposerHandle | null>;
+    /**
+     * Called instead of queueing when the human types while the running agent is holding a question
+     * open in the transcript (an interactive surface whose call to `deliverTypedAnswer.toolName` has
+     * not returned — `isAwaitingTypedAnswer`) and the turn carries no attachments. `'delivered'` clears the draft
+     * (only if unchanged since it went out); any other outcome, or a throw, leaves the draft in place with a
+     * notice and NEVER queues it — a queued answer would go out after the run ends as a new, paid run
+     * answering nothing. A draft typed while the question waited stays held after it closes, until the
+     * human clears it or picks "Send as a new message" (`useChatPane`'s `sendAsNewMessage`).
+     *
+     * Omit it and typing while a run streams queues exactly as before.
+     */
+    deliverTypedAnswer?: DeliverTypedAnswer;
     placeholder?: string;
     /**
      * Rotating composer suggestions, cycled every few seconds in place of one fixed `placeholder` —

package/dist/react/hooks/useSurfaceExpiry.d.ts

@@ -0,0 +1,20 @@
+import { type SurfaceExpiry } from '../../core/index.js';
+/** The clock port: the current time, and a repeating ticker that returns its own stop function. */
+export interface SurfaceExpiryClock {
+    nowMs(): number;
+    every(intervalMs: number, tick: () => void): () => void;
+}
+/** The wall clock and `setInterval`; the default when a caller injects none. */
+export declare const SYSTEM_SURFACE_EXPIRY_CLOCK: SurfaceExpiryClock;
+/**
+ * @param input.expiresAtMs - The card's deadline (epoch ms), or `undefined` when it has none.
+ * @param options.clock - Time source and ticker. Defaults to {@link SYSTEM_SURFACE_EXPIRY_CLOCK}.
+ * @returns The deadline's state at the last tick, or `undefined` when there is no deadline.
+ * @complexity O(1) per render; one ticker while live.
+ */
+export declare function useSurfaceExpiry({ expiresAtMs }: {
+    expiresAtMs: number | undefined;
+}, { clock }?: {
+    clock?: SurfaceExpiryClock;
+}): SurfaceExpiry | undefined;
+//# sourceMappingURL=useSurfaceExpiry.d.ts.map

package/dist/react/hooks/useSurfaceExpiry.js

@@ -0,0 +1,35 @@
+/**
+ * @module useSurfaceExpiry
+ *
+ * The live countdown for a pending MCP-UI card: `describeSurfaceExpiry` re-read once a second on an
+ * injected clock. Ticks only while the card is answerable and has a deadline; an expired card or one
+ * without a deadline runs no timer.
+ */
+import { useEffect, useState } from 'react';
+import { describeSurfaceExpiry, SURFACE_EXPIRY_TICK_MS } from '../../core/index.js';
+/** The wall clock and `setInterval`; the default when a caller injects none. */
+export const SYSTEM_SURFACE_EXPIRY_CLOCK = {
+    nowMs: () => Date.now(),
+    every: (intervalMs, tick) => {
+        const timer = setInterval(tick, intervalMs);
+        return () => clearInterval(timer);
+    },
+};
+/**
+ * @param input.expiresAtMs - The card's deadline (epoch ms), or `undefined` when it has none.
+ * @param options.clock - Time source and ticker. Defaults to {@link SYSTEM_SURFACE_EXPIRY_CLOCK}.
+ * @returns The deadline's state at the last tick, or `undefined` when there is no deadline.
+ * @complexity O(1) per render; one ticker while live.
+ */
+export function useSurfaceExpiry({ expiresAtMs }, { clock = SYSTEM_SURFACE_EXPIRY_CLOCK } = {}) {
+    const [nowMs, setNowMs] = useState(() => clock.nowMs());
+    const expiry = expiresAtMs === undefined ? undefined : describeSurfaceExpiry({ expiresAtMs, nowMs });
+    const live = expiry?.expired === false;
+    useEffect(() => {
+        if (!live)
+            return undefined;
+        return clock.every(SURFACE_EXPIRY_TICK_MS, () => setNowMs(clock.nowMs()));
+    }, [live, clock]);
+    return expiry;
+}
+//# sourceMappingURL=useSurfaceExpiry.js.map

package/dist/react/index.d.ts

@@ -36,8 +36,8 @@ export type { ExtEventRenderProps, ExtEventRenderer, ExtEventRendererOptions, Ex
  * This alias has no removal date scheduled yet; see `chat-pane.ts` for the canonical surface and
  * the module doc there for why the split exists.
  */
-export { AgentRuntimePicker, CHAT_PANE_AGENT_TOOLS, ChatPane, createDaemonAttachmentUploader, createMcpUiToolCaller, defaultChatPaneSelection, orderChatPaneAgents, resolveChatPaneSelection, useChatPane, useChatPaneAgentControl, useChatPaneRuntimeInventory, useChatPaneWorkingDirectory, } from './chat-pane.js';
-export type { AgentRuntimePickerProps, ByokRuntimeSummary, ChatPaneActivity, ChatPaneAgent, ChatPaneAgentBridgeAccess, ChatPaneAgentControlOptions, ChatPaneAgentOption, ChatPaneAgentSelection, ChatPaneAgentToolAction, ChatPaneAgentToolDef, ChatPaneAgentToolInputSchema, ChatPaneAgentToolRisk, ChatPaneAttachmentUploadOptions, ChatPaneComposerHandle, ChatPaneProps, ChatPaneRunContext, ChatPaneRunContextInput, ChatPaneRuntimeAccess, ChatPaneVariant, ChatPaneWorkingDirectoryAccess, CreateDaemonAttachmentUploaderOptions, CreateMcpUiToolCallerOptions, McpUiToolCallRequest, RuntimePickerPlacement, UseChatPaneAgentControlOptions, UseChatPaneOptions, UseChatPaneResult, UseChatPaneRuntimeInventoryOptions, UseChatPaneRuntimeInventoryResult, UseChatPaneWorkingDirectoryOptions, UseChatPaneWorkingDirectoryResult, } from './chat-pane.js';
+export { AgentRuntimePicker, CHAT_PANE_AGENT_TOOLS, ChatPane, createDaemonAttachmentUploader, createMcpUiToolCaller, createTypedAnswerPoster, defaultChatPaneSelection, orderChatPaneAgents, resolveChatPaneSelection, useChatPane, useChatPaneAgentControl, useChatPaneRuntimeInventory, useChatPaneWorkingDirectory, } from './chat-pane.js';
+export type { AgentRuntimePickerProps, ByokRuntimeSummary, ChatPaneActivity, ChatPaneAgent, ChatPaneAgentBridgeAccess, ChatPaneAgentControlOptions, ChatPaneAgentOption, ChatPaneAgentSelection, ChatPaneAgentToolAction, ChatPaneAgentToolDef, ChatPaneAgentToolInputSchema, ChatPaneAgentToolRisk, ChatPaneAttachmentUploadOptions, ChatPaneComposerHandle, ChatPaneProps, ChatPaneRunContext, ChatPaneRunContextInput, ChatPaneRuntimeAccess, ChatPaneVariant, ChatPaneWorkingDirectoryAccess, CreateDaemonAttachmentUploaderOptions, CreateMcpUiToolCallerOptions, CreateTypedAnswerPosterOptions, DeliverTypedAnswer, McpUiToolCallRequest, RuntimePickerPlacement, TypedAnswerDelivery, TypedAnswerNotice, UseChatPaneAgentControlOptions, UseChatPaneOptions, UseChatPaneResult, UseChatPaneRuntimeInventoryOptions, UseChatPaneRuntimeInventoryResult, UseChatPaneWorkingDirectoryOptions, UseChatPaneWorkingDirectoryResult, } from './chat-pane.js';
 export { useRunStream, } from './hooks/useRunStream.js';
 export type { RunStreamState, RunStreamStatus, StartRunOptions, UseRunStreamResult, } from './hooks/useRunStream.js';
 export { useConversation, } from './hooks/useConversation.js';
@@ -48,6 +48,8 @@ export { useToolTimeline, } from './hooks/useToolTimeline.js';
 export type { ToolTimelineRow, UseToolTimelineOptions, UseToolTimelineResult, } from './hooks/useToolTimeline.js';
 export { useExtEventGroups, } from './hooks/useExtEventGroups.js';
 export type { ExtEventGroup, } from './hooks/useExtEventGroups.js';
+export { SYSTEM_SURFACE_EXPIRY_CLOCK, useSurfaceExpiry, } from './hooks/useSurfaceExpiry.js';
+export type { SurfaceExpiryClock, } from './hooks/useSurfaceExpiry.js';
 export { usePinnedTodos, } from './hooks/usePinnedTodos.js';
 export type { UsePinnedTodosResult, } from './hooks/usePinnedTodos.js';
 export { parseSubmittedAnswers, useQuestionForms, } from './hooks/useQuestionForms.js';

package/dist/react/index.js

@@ -26,12 +26,13 @@ export { clearExtEventRenderers, extEventSlot, getExtEventRenderer, registerExtE
  * This alias has no removal date scheduled yet; see `chat-pane.ts` for the canonical surface and
  * the module doc there for why the split exists.
  */
-export { AgentRuntimePicker, CHAT_PANE_AGENT_TOOLS, ChatPane, createDaemonAttachmentUploader, createMcpUiToolCaller, defaultChatPaneSelection, orderChatPaneAgents, resolveChatPaneSelection, useChatPane, useChatPaneAgentControl, useChatPaneRuntimeInventory, useChatPaneWorkingDirectory, } from './chat-pane.js';
+export { AgentRuntimePicker, CHAT_PANE_AGENT_TOOLS, ChatPane, createDaemonAttachmentUploader, createMcpUiToolCaller, createTypedAnswerPoster, defaultChatPaneSelection, orderChatPaneAgents, resolveChatPaneSelection, useChatPane, useChatPaneAgentControl, useChatPaneRuntimeInventory, useChatPaneWorkingDirectory, } from './chat-pane.js';
 export { useRunStream, } from './hooks/useRunStream.js';
 export { useConversation, } from './hooks/useConversation.js';
 export { useComposer, } from './hooks/useComposer.js';
 export { useToolTimeline, } from './hooks/useToolTimeline.js';
 export { useExtEventGroups, } from './hooks/useExtEventGroups.js';
+export { SYSTEM_SURFACE_EXPIRY_CLOCK, useSurfaceExpiry, } from './hooks/useSurfaceExpiry.js';
 export { usePinnedTodos, } from './hooks/usePinnedTodos.js';
 export { parseSubmittedAnswers, useQuestionForms, } from './hooks/useQuestionForms.js';
 export { useArtifactStream, } from './hooks/useArtifactStream.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/chat",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Jini's chat/artifact frontend, consolidated into one package with two subpaths: framework-free chat vocabulary and pure parsers in `/core`, headless hooks + presentational components + slots in `/react`. Import only the layer you need.",
   "license": "Apache-2.0",
   "repository": {
@@ -145,15 +145,15 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@jini-ai/protocol": "0.4.0",
-    "@jini-ai/agentic": "0.4.0",
-    "@jini-ai/ui": "0.4.0",
-    "@jini-ai/core": "0.4.0"
+    "@jini-ai/agentic": "^0.4.1",
+    "@jini-ai/ui": "^0.4.3",
+    "@jini-ai/core": "^0.4.1",
+    "@jini-ai/protocol": "^0.4.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0",
-    "@jini-ai/db": "^0.2.0",
+    "@jini-ai/db": "^0.2.0 || ^0.3.0",
     "kysely": "^0.29.6",
     "better-sqlite3": "^13.0.0",
     "@electric-sql/pglite": "0.5.8",
@@ -238,8 +238,8 @@
     "@electric-sql/pglite": "0.5.8",
     "pg": "8.23.0",
     "@ag-ui/core": "0.0.58",
-    "@jini-ai/db": "0.2.0",
-    "@jini-ai/agent-runtime": "0.4.0"
+    "@jini-ai/agent-runtime": "0.4.0",
+    "@jini-ai/db": "0.3.0"
   },
   "typesVersions": {
     "*": {