diff --git a/client/src/common/a11y.ts b/client/src/common/a11y.ts index 0a0e56eab2..01673cf542 100644 --- a/client/src/common/a11y.ts +++ b/client/src/common/a11y.ts @@ -1,6 +1,2 @@ -export interface AnnounceOptions { - message: string; - isStatus?: boolean; -} - -export const MESSAGE_UPDATE_INTERVAL = 7000; +export { MESSAGE_UPDATE_INTERVAL } from '@librechat/chat'; +export type { AnnounceOptions } from '@librechat/chat'; diff --git a/client/src/common/ptc.ts b/client/src/common/ptc.ts index bf3047d23d..5fa86b1cf2 100644 --- a/client/src/common/ptc.ts +++ b/client/src/common/ptc.ts @@ -1,29 +1 @@ -import type { PtcToolCallStatus } from 'librechat-data-provider'; - -/** - * A row's outcome. Widens the wire status with `interrupted`, which the - * backend never sends: it is what the client concludes locally about a call - * that was still running when a stream gap swallowed its settling event. - */ -export type PtcTraceStatus = PtcToolCallStatus | 'interrupted'; - -/** One tool call a programmatic (PTC) program made from inside the sandbox. */ -export interface PtcTraceEntry { - /** Stable id from the backend; the settle event updates this row in place. */ - callId: string; - /** Inner tool id, e.g. `search_code_mcp_github`. */ - name: string; - status: PtcTraceStatus; - /** `key=value` preview of the call's input. */ - args?: string; - /** Truncated failure message on a failed call. */ - error?: string; - durationMs?: number; -} - -/** One PTC program's trace: the retained tail plus what the cap discarded. */ -export interface PtcTrace { - entries: PtcTraceEntry[]; - /** Rows evicted by the trace cap (`PTC_TRACE_MAX_ENTRIES`), so the cap is never silent. */ - dropped: number; -} +export type { PtcTrace, PtcTraceEntry, PtcTraceStatus } from '@librechat/chat'; diff --git a/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts b/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts index 451968d3b0..d59f60b0e4 100644 --- a/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts +++ b/client/src/hooks/SSE/__tests__/stepEquivalence.spec.ts @@ -2,6 +2,7 @@ import React from 'react'; import { createHash } from 'crypto'; import { RecoilRoot } from 'recoil'; import { createStore, Provider } from 'jotai'; +import { useStepHandler } from '@librechat/chat/react'; import { renderHook, act } from '@testing-library/react'; import { Constants, @@ -27,7 +28,6 @@ import type { import type { StepEvent } from '@librechat/chat'; import { ptcTraceByToolCallId, ptcTraceKey } from '~/hooks/SSE/ptc'; import { sandboxStartingByToolCallId } from '~/hooks/SSE/sandbox'; -import useStepHandler from '~/hooks/SSE/useStepHandler'; /** * Equivalence table for the step reducer. Each row is an event sequence shaped like a recorded diff --git a/client/src/hooks/SSE/__tests__/titles.spec.tsx b/client/src/hooks/SSE/__tests__/titles.spec.tsx index 4602270c25..0d9cecaa7a 100644 --- a/client/src/hooks/SSE/__tests__/titles.spec.tsx +++ b/client/src/hooks/SSE/__tests__/titles.spec.tsx @@ -14,9 +14,12 @@ jest.mock('~/hooks/AuthContext', () => ({ useAuthContext: () => ({ token: 'test' jest.mock('~/Providers', () => ({ useLiveAnnouncer: () => ({ announcePolite: jest.fn() }) })); jest.mock('../useContentHandler', () => () => ({})); jest.mock('../useAttachmentHandler', () => () => jest.fn()); -jest.mock('../useStepHandler', () => () => ({ - resetSubagentAtoms: jest.fn(), - resetPtcAtoms: jest.fn(), +jest.mock('@librechat/chat/react', () => ({ + ...jest.requireActual('@librechat/chat/react'), + useStepHandler: () => ({ + resetSubagentAtoms: jest.fn(), + resetPtcAtoms: jest.fn(), + }), })); const initialConversation = { diff --git a/client/src/hooks/SSE/__tests__/useEventHandlers.cancel.spec.tsx b/client/src/hooks/SSE/__tests__/useEventHandlers.cancel.spec.tsx index 6c9099f4df..e7dccbc739 100644 --- a/client/src/hooks/SSE/__tests__/useEventHandlers.cancel.spec.tsx +++ b/client/src/hooks/SSE/__tests__/useEventHandlers.cancel.spec.tsx @@ -38,15 +38,18 @@ jest.mock('../useContentHandler', () => () => ({ resetContentHandler: jest.fn(), })); jest.mock('../useAttachmentHandler', () => () => jest.fn()); -jest.mock('../useStepHandler', () => () => ({ - stepHandler: jest.fn(), - clearStepMaps: jest.fn(), - resetSubagentAtoms: mockResetSubagentAtoms, - resetPtcAtoms: mockResetPtcAtoms, - prunePtcTraces: jest.fn(), - syncStepMessage: jest.fn(), - cancelPendingDeltaFlush: jest.fn(), - flushPendingDeltas: jest.fn(), +jest.mock('@librechat/chat/react', () => ({ + ...jest.requireActual('@librechat/chat/react'), + useStepHandler: () => ({ + stepHandler: jest.fn(), + clearStepMaps: jest.fn(), + resetSubagentAtoms: mockResetSubagentAtoms, + resetPtcAtoms: mockResetPtcAtoms, + prunePtcTraces: jest.fn(), + syncStepMessage: jest.fn(), + cancelPendingDeltaFlush: jest.fn(), + flushPendingDeltas: jest.fn(), + }), })); jest.mock('~/data-provider', () => ({ ...jest.requireActual('~/data-provider/CodeEnvironments'), diff --git a/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts b/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts index 89fbe9699a..2772f43797 100644 --- a/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts +++ b/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts @@ -1,5 +1,6 @@ import React from 'react'; import { RecoilRoot } from 'recoil'; +import { useStepHandler } from '@librechat/chat/react'; import { renderHook, act } from '@testing-library/react'; import { useStore, useAtomValue, createStore, Provider as JotaiProvider } from 'jotai'; import { @@ -34,7 +35,6 @@ import type { PtcTrace, PtcTraceEntry } from '~/common'; import { ptcTraceByToolCallId, ptcTraceKey, PTC_TRACE_MAX_ENTRIES } from '~/hooks/SSE/ptc'; import { sandboxStartingByToolCallId } from '~/hooks/SSE/sandbox'; import { resolveAskUserQuestionPart } from '~/utils/approval'; -import useStepHandler from '~/hooks/SSE/useStepHandler'; import { IsolatedAtomStore } from 'test/harness'; /** `Constants` is a heterogeneous enum (`string | number`); annotate as diff --git a/client/src/hooks/SSE/__tests__/workspace.spec.tsx b/client/src/hooks/SSE/__tests__/workspace.spec.tsx index 51fd3dfca1..b0e70bfac9 100644 --- a/client/src/hooks/SSE/__tests__/workspace.spec.tsx +++ b/client/src/hooks/SSE/__tests__/workspace.spec.tsx @@ -38,9 +38,12 @@ jest.mock('~/Providers', () => ({ })); jest.mock('~/hooks/SSE/useContentHandler', () => () => ({})); jest.mock('~/hooks/SSE/useAttachmentHandler', () => () => jest.fn()); -jest.mock('~/hooks/SSE/useStepHandler', () => () => ({ - resetSubagentAtoms: mockReset, - resetPtcAtoms: mockReset, +jest.mock('@librechat/chat/react', () => ({ + ...jest.requireActual('@librechat/chat/react'), + useStepHandler: () => ({ + resetSubagentAtoms: mockReset, + resetPtcAtoms: mockReset, + }), })); jest.mock('~/hooks/Agents/workspacePreferences', () => ({ useWorkspacePreferences: () => ({ get: () => undefined }), diff --git a/client/src/hooks/SSE/index.ts b/client/src/hooks/SSE/index.ts index f2438e42ba..a2d68c10e4 100644 --- a/client/src/hooks/SSE/index.ts +++ b/client/src/hooks/SSE/index.ts @@ -1,7 +1,7 @@ export { default as useSSE } from './useSSE'; export { useResumableSSE, useAdaptiveSSE } from '@librechat/chat/react'; export { default as useResumeOnLoad } from './useResumeOnLoad'; -export { default as useStepHandler } from './useStepHandler'; +export { useStepHandler } from '@librechat/chat/react'; export { default as useUsageHandler } from './useUsageHandler'; export { default as useContentHandler } from './useContentHandler'; export { default as useAttachmentHandler } from './useAttachmentHandler'; diff --git a/client/src/hooks/SSE/ptc.ts b/client/src/hooks/SSE/ptc.ts index b1b9dba668..6a6ffc68b6 100644 --- a/client/src/hooks/SSE/ptc.ts +++ b/client/src/hooks/SSE/ptc.ts @@ -1,34 +1,6 @@ -import { atom } from 'jotai'; -import { atomFamily } from 'jotai/utils'; -import type { PtcTrace } from '~/common'; - -/** - * Stable identity for one PTC invocation in its parent message. Providers - * reuse `tool_call_id` across turns and agents, so the raw id is not - * sufficient identity for live progress — the same rule `subagentProgressKey` - * exists for. Without the message scope, a later program's rows would land in - * an earlier card that happened to share `call_0`. - */ -export const ptcTraceKey = (parentMessageId: string, toolCallId: string) => - `${parentMessageId}\u0000${toolCallId}`; - -/** - * Rolling cap on retained rows. A program looping over a large collection can - * make thousands of inner calls; without a bound, every event would copy an - * ever-growing array and the card would render a row per call. - */ -export const PTC_TRACE_MAX_ENTRIES = 100; - -/** Shared empty value — one reference, so untouched atoms compare equal. */ -export const EMPTY_PTC_TRACE: PtcTrace = { entries: [], dropped: 0 }; - -/** - * Live trace of the inner tool calls made by one PTC run step, in the order - * the sandbox started them (`on_ptc_tool_call` SSE events). Keyed by - * {@link ptcTraceKey} — one concrete invocation in one message. - * - * Session-scoped like the subagent ticker: inner calls open no run step, so - * nothing persists them on the message. Cleared on conversation switch rather - * than at run boundaries, so a finished program's trace stays readable. - */ -export const ptcTraceByToolCallId = atomFamily((_key: string) => atom(EMPTY_PTC_TRACE)); +export { + ptcTraceKey, + EMPTY_PTC_TRACE, + ptcTraceByToolCallId, + PTC_TRACE_MAX_ENTRIES, +} from '@librechat/chat/react'; diff --git a/client/src/hooks/SSE/sandbox.ts b/client/src/hooks/SSE/sandbox.ts index 30e7d8ad2a..96b79cdef3 100644 --- a/client/src/hooks/SSE/sandbox.ts +++ b/client/src/hooks/SSE/sandbox.ts @@ -1,11 +1 @@ -import { atom } from 'jotai'; -import { atomFamily } from 'jotai/utils'; - -/** - * True while the backend reported the stateful code sandbox is cold-booting - * for this tool call (`on_sandbox_starting` SSE event). Keyed by - * `tool_call_id`; `ExecuteCode`/`BashCall` swap their in-progress label to a - * "starting sandbox" message while set. Cleared when the tool call's run - * step completes. - */ -export const sandboxStartingByToolCallId = atomFamily((_toolCallId: string) => atom(false)); +export { sandboxStartingByToolCallId } from '@librechat/chat/react'; diff --git a/client/src/hooks/SSE/useEventHandlers.ts b/client/src/hooks/SSE/useEventHandlers.ts index b1ff0898e3..22206a9388 100644 --- a/client/src/hooks/SSE/useEventHandlers.ts +++ b/client/src/hooks/SSE/useEventHandlers.ts @@ -5,6 +5,7 @@ import { buildRecoveryPreset } from '@librechat/chat'; import { useQueryClient } from '@tanstack/react-query'; import { useParams, useNavigate, useLocation } from 'react-router-dom'; import { + useStepHandler, submissionStartFamily, getReasoningStateKey, pendingQuotesByConvoId, @@ -19,7 +20,6 @@ import { getFailedCodeDecisionRequest } from '~/hooks/Agents/codeDecision'; import { shouldResetSubagentAtomsOnConversationChange } from './cleanup'; import useAttachmentHandler from '~/hooks/SSE/useAttachmentHandler'; import useContentHandler from '~/hooks/SSE/useContentHandler'; -import useStepHandler from '~/hooks/SSE/useStepHandler'; import { useApplyAgentTemplate } from '~/hooks/Agents'; import { useLiveAnnouncer } from '~/Providers'; import useTurnHandlers from './opening'; diff --git a/packages/chat/src/core/a11y.ts b/packages/chat/src/core/a11y.ts new file mode 100644 index 0000000000..0a0e56eab2 --- /dev/null +++ b/packages/chat/src/core/a11y.ts @@ -0,0 +1,6 @@ +export interface AnnounceOptions { + message: string; + isStatus?: boolean; +} + +export const MESSAGE_UPDATE_INTERVAL = 7000; diff --git a/packages/chat/src/core/index.ts b/packages/chat/src/core/index.ts index d3c29f4d63..35a90defa0 100644 --- a/packages/chat/src/core/index.ts +++ b/packages/chat/src/core/index.ts @@ -17,5 +17,7 @@ export * from './regenerate'; export * from './content'; export * from './turns'; export * from './parts'; +export * from './a11y'; +export * from './ptc'; export * from './subagents'; export { strongDirection } from './direction'; diff --git a/packages/chat/src/core/ptc.ts b/packages/chat/src/core/ptc.ts new file mode 100644 index 0000000000..bf3047d23d --- /dev/null +++ b/packages/chat/src/core/ptc.ts @@ -0,0 +1,29 @@ +import type { PtcToolCallStatus } from 'librechat-data-provider'; + +/** + * A row's outcome. Widens the wire status with `interrupted`, which the + * backend never sends: it is what the client concludes locally about a call + * that was still running when a stream gap swallowed its settling event. + */ +export type PtcTraceStatus = PtcToolCallStatus | 'interrupted'; + +/** One tool call a programmatic (PTC) program made from inside the sandbox. */ +export interface PtcTraceEntry { + /** Stable id from the backend; the settle event updates this row in place. */ + callId: string; + /** Inner tool id, e.g. `search_code_mcp_github`. */ + name: string; + status: PtcTraceStatus; + /** `key=value` preview of the call's input. */ + args?: string; + /** Truncated failure message on a failed call. */ + error?: string; + durationMs?: number; +} + +/** One PTC program's trace: the retained tail plus what the cap discarded. */ +export interface PtcTrace { + entries: PtcTraceEntry[]; + /** Rows evicted by the trace cap (`PTC_TRACE_MAX_ENTRIES`), so the cap is never silent. */ + dropped: number; +} diff --git a/packages/chat/src/react/stream/index.ts b/packages/chat/src/react/stream/index.ts index 350dabbfa4..5ac49fe7d8 100644 --- a/packages/chat/src/react/stream/index.ts +++ b/packages/chat/src/react/stream/index.ts @@ -1,4 +1,8 @@ export { default as useAdaptiveSSE } from './adaptive'; export { default as useResumableSSE } from './resumable'; export { StreamHostProvider, useStreamHost } from './host'; +export { useStepHandler } from './step'; +export type { StepHandlers } from './step'; +export { sandboxStartingByToolCallId } from './sandbox'; +export { ptcTraceKey, ptcTraceByToolCallId, EMPTY_PTC_TRACE, PTC_TRACE_MAX_ENTRIES } from './ptc'; export type { StreamHost, StreamChat, ResumableServices, ResumableStreamParams } from './host'; diff --git a/packages/chat/src/react/stream/ptc.ts b/packages/chat/src/react/stream/ptc.ts new file mode 100644 index 0000000000..20bffeac38 --- /dev/null +++ b/packages/chat/src/react/stream/ptc.ts @@ -0,0 +1,37 @@ +import { atom } from 'jotai'; +import { atomFamily } from 'jotai/utils'; +import type { Family } from '../steer/family'; +import type { PtcTrace } from '../../core'; + +/** + * Stable identity for one PTC invocation in its parent message. Providers + * reuse `tool_call_id` across turns and agents, so the raw id is not + * sufficient identity for live progress, the same rule `subagentProgressKey` + * exists for. Without the message scope, a later program's rows would land in + * an earlier card that happened to share `call_0`. + */ +export const ptcTraceKey = (parentMessageId: string, toolCallId: string): string => + `${parentMessageId}\u0000${toolCallId}`; + +/** + * Rolling cap on retained rows. A program looping over a large collection can + * make thousands of inner calls; without a bound, every event would copy an + * ever-growing array and the card would render a row per call. + */ +export const PTC_TRACE_MAX_ENTRIES = 100; + +/** Shared empty value: one reference, so untouched atoms compare equal. */ +export const EMPTY_PTC_TRACE: PtcTrace = { entries: [], dropped: 0 }; + +/** + * Live trace of the inner tool calls made by one PTC run step, in the order + * the sandbox started them (`on_ptc_tool_call` SSE events). Keyed by + * {@link ptcTraceKey}, one concrete invocation in one message. + * + * Session-scoped like the subagent ticker: inner calls open no run step, so + * nothing persists them on the message. Cleared on conversation switch rather + * than at run boundaries, so a finished program's trace stays readable. + */ +export const ptcTraceByToolCallId: Family = atomFamily((_key: string) => + atom(EMPTY_PTC_TRACE), +); diff --git a/packages/chat/src/react/stream/sandbox.ts b/packages/chat/src/react/stream/sandbox.ts new file mode 100644 index 0000000000..4ccfff7da6 --- /dev/null +++ b/packages/chat/src/react/stream/sandbox.ts @@ -0,0 +1,14 @@ +import { atom } from 'jotai'; +import { atomFamily } from 'jotai/utils'; +import type { Family } from '../steer/family'; + +/** + * True while the backend reported the stateful code sandbox is cold-booting + * for this tool call (`on_sandbox_starting` SSE event). Keyed by + * `tool_call_id`; `ExecuteCode`/`BashCall` swap their in-progress label to a + * "starting sandbox" message while set. Cleared when the tool call's run + * step completes. + */ +export const sandboxStartingByToolCallId: Family = atomFamily((_toolCallId: string) => + atom(false), +); diff --git a/client/src/hooks/SSE/useStepHandler.ts b/packages/chat/src/react/stream/step.ts similarity index 95% rename from client/src/hooks/SSE/useStepHandler.ts rename to packages/chat/src/react/stream/step.ts index 53e9b437a6..af6b3e4bbf 100644 --- a/client/src/hooks/SSE/useStepHandler.ts +++ b/packages/chat/src/react/stream/step.ts @@ -1,14 +1,12 @@ import { useCallback, useRef } from 'react'; import { useStore } from 'jotai'; -import { - reduceStep, - flushSummary, - flushResponses, - resetStreamState, - syncStreamMessage, - createStreamState, - subagentProgressKey, -} from '@librechat/chat'; +import type { + TMessage, + EventSubmission, + SubagentUpdateEvent, + PtcToolCallEvent, +} from 'librechat-data-provider'; +import type { StepEvent, StepEffect, StepContext, StreamState, AnnounceOptions } from '../../core'; import { activeSubagentPanel, closeParentSubagentProgress, @@ -19,18 +17,19 @@ import { subagentParentStreamOpenByToolCallId, subagentProgressByToolCallId, takeRegisteredSubagentProgressKeys, -} from '@librechat/chat/react'; -import type { - TMessage, - EventSubmission, - SubagentUpdateEvent, - PtcToolCallEvent, -} from 'librechat-data-provider'; -import type { StepEvent, StepEffect, StepContext, StreamState } from '@librechat/chat'; -import type { AnnounceOptions } from '~/common'; +} from '../subagents/state'; +import { + reduceStep, + flushSummary, + flushResponses, + resetStreamState, + syncStreamMessage, + createStreamState, + subagentProgressKey, + MESSAGE_UPDATE_INTERVAL, +} from '../../core'; import { ptcTraceByToolCallId, EMPTY_PTC_TRACE, PTC_TRACE_MAX_ENTRIES, ptcTraceKey } from './ptc'; import { sandboxStartingByToolCallId } from './sandbox'; -import { MESSAGE_UPDATE_INTERVAL } from '~/common'; type TUseStepHandler = { announcePolite: (options: AnnounceOptions) => void; @@ -46,14 +45,26 @@ type TUseStepHandler = { onSubagentIndexChange?: (conversationId: string) => void; }; -export default function useStepHandler({ +/** The handlers a pane's stream feeds run steps through, and the resets around a run. */ +export type StepHandlers = { + stepHandler: (stepEvent: StepEvent, submission: EventSubmission) => void; + clearStepMaps: () => void; + resetSubagentAtoms: (options?: { preserveSelectedTask?: boolean }) => void; + resetPtcAtoms: () => void; + prunePtcTraces: () => void; + syncStepMessage: (message: TMessage) => void; + cancelPendingDeltaFlush: () => void; + flushPendingDeltas: () => void; +}; + +export function useStepHandler({ setMessages, getMessages, announcePolite, lastAnnouncementTimeRef, onSkillAuthoringComplete, onSubagentIndexChange, -}: TUseStepHandler) { +}: TUseStepHandler): StepHandlers { const subagentStore = useStore(); const stream = useRef(createStreamState()); /** Coalesces rapid-fire summarize delta renders into a single rAF frame */