@perstack/react 0.0.58 → 0.0.59

package/dist/src/index.js

@@ -1,5 +1,661 @@
-// Hooks
-export { useJobStream, useJobStreams, useRun, } from "./hooks/index.js";
-// Utils
-export { createInitialActivityProcessState, groupActivitiesByRun, processRunEventToActivity, toolToActivity, } from "./utils/index.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { BASE_SKILL_PREFIX, createBaseToolActivity, createGeneralToolActivity } from "@perstack/core";
+
+//#region src/utils/stream.ts
+const isAbortError = (err) => err instanceof DOMException && err.name === "AbortError";
+/**
+* Consumes an SSE stream with abort-safe iteration and error normalization.
+*
+* Handles the connection lifecycle shared by all streaming hooks:
+* 1. Calls `connect` to obtain an async iterable
+* 2. Iterates events, stopping on signal abort
+* 3. Filters out AbortError (normal cleanup), surfaces all others
+*/
+async function consumeStream(connect, jobId, signal, onEvent) {
+	const events = await connect(jobId, signal);
+	for await (const event of events) {
+		if (signal.aborted) break;
+		onEvent(event);
+	}
+}
+
+//#endregion
+//#region src/utils/event-to-activity.ts
+/**
+* Converts a tool call and result to an Activity.
+* Delegates to core's createBaseToolActivity/createGeneralToolActivity to avoid duplication.
+*/
+function toolToActivity(toolCall, toolResult, reasoning, meta) {
+	const { skillName, toolName } = toolCall;
+	return {
+		...skillName.startsWith(BASE_SKILL_PREFIX) ? createBaseToolActivity(toolName, toolCall, toolResult, reasoning) : createGeneralToolActivity(skillName, toolName, toolCall, toolResult, reasoning),
+		id: meta.id,
+		expertKey: meta.expertKey,
+		runId: meta.runId,
+		previousActivityId: meta.previousActivityId,
+		delegatedBy: meta.delegatedBy
+	};
+}
+function createInitialActivityProcessState() {
+	return {
+		tools: /* @__PURE__ */ new Map(),
+		runStates: /* @__PURE__ */ new Map()
+	};
+}
+function getOrCreateRunState(state, runId, expertKey) {
+	let runState = state.runStates.get(runId);
+	if (!runState) {
+		runState = {
+			expertKey,
+			queryLogged: false,
+			completionLogged: false,
+			isComplete: false,
+			pendingDelegateCount: 0
+		};
+		state.runStates.set(runId, runState);
+	}
+	return runState;
+}
+const isRunEvent = (event) => "type" in event && "expertKey" in event;
+const isCompleteStreamingReasoningEvent = (event) => "type" in event && event.type === "completeStreamingReasoning";
+const isToolCallsEvent = (event) => event.type === "callTools" && "toolCalls" in event;
+const isStopRunByDelegateEvent = (event) => event.type === "stopRunByDelegate" && "checkpoint" in event;
+const isStopRunByInteractiveToolEvent = (event) => event.type === "stopRunByInteractiveTool" && "checkpoint" in event;
+const isToolResultsEvent = (event) => event.type === "resolveToolResults" && "toolResults" in event;
+/**
+* Wraps multiple activities in a ParallelActivitiesGroup with shared reasoning.
+* If only one activity, returns it directly.
+*/
+function wrapInGroupIfParallel(activities, reasoning, meta) {
+	if (activities.length <= 1) return activities;
+	const activitiesWithoutReasoning = activities.map((a) => {
+		const { reasoning: _, ...rest } = a;
+		return rest;
+	});
+	return [{
+		type: "parallelGroup",
+		id: `parallel-${activities[0].id}`,
+		expertKey: meta.expertKey,
+		runId: meta.runId,
+		reasoning,
+		activities: activitiesWithoutReasoning
+	}];
+}
+/**
+* Processes a RunEvent and produces Activity or ParallelActivitiesGroup items.
+* Only processes RunEvent (state machine transitions), not RuntimeEvent.
+*
+* @param state - Mutable processing state
+* @param event - The event to process
+* @param addActivity - Callback to add a new Activity or ParallelActivitiesGroup
+*/
+function processRunEventToActivity(state, event, addActivity) {
+	if (isCompleteStreamingReasoningEvent(event)) {
+		const { runId, text, expertKey } = event;
+		const runState = state.runStates.get(runId);
+		if (runState) runState.completedReasoning = text;
+		else state.runStates.set(runId, {
+			expertKey,
+			queryLogged: false,
+			completionLogged: false,
+			isComplete: false,
+			pendingDelegateCount: 0,
+			completedReasoning: text
+		});
+		return;
+	}
+	if (!isRunEvent(event)) return;
+	const runState = getOrCreateRunState(state, event.runId, event.expertKey);
+	if (event.type === "startRun") {
+		const startRunEvent = event;
+		const queryText = startRunEvent.inputMessages.find((m) => m.type === "userMessage")?.contents?.find((c) => c.type === "textPart")?.text;
+		if (!runState.delegatedBy) {
+			const delegatedByInfo = startRunEvent.initialCheckpoint?.delegatedBy;
+			if (delegatedByInfo) runState.delegatedBy = {
+				expertKey: delegatedByInfo.expert.key,
+				runId: delegatedByInfo.runId
+			};
+		}
+		const isDelegationReturn = startRunEvent.initialCheckpoint?.status === "stoppedByDelegate" || startRunEvent.initialCheckpoint?.status === "stoppedByInteractiveTool";
+		if (queryText && !runState.queryLogged && !isDelegationReturn) {
+			const activityId = `query-${event.runId}`;
+			addActivity({
+				type: "query",
+				id: activityId,
+				expertKey: event.expertKey,
+				runId: event.runId,
+				previousActivityId: runState.lastActivityId,
+				delegatedBy: runState.delegatedBy,
+				text: queryText
+			});
+			runState.lastActivityId = activityId;
+			runState.queryLogged = true;
+		}
+		return;
+	}
+	if (event.type === "resumeFromStop") {
+		if (!runState.delegatedBy) {
+			const delegatedByInfo = event.checkpoint?.delegatedBy;
+			if (delegatedByInfo) runState.delegatedBy = {
+				expertKey: delegatedByInfo.expert.key,
+				runId: delegatedByInfo.runId
+			};
+		}
+		return;
+	}
+	if (event.type === "retry") {
+		const retryEvent = event;
+		const activityId = `retry-${event.id}`;
+		addActivity({
+			type: "retry",
+			id: activityId,
+			expertKey: event.expertKey,
+			runId: event.runId,
+			previousActivityId: runState.lastActivityId,
+			delegatedBy: runState.delegatedBy,
+			reasoning: runState.completedReasoning,
+			error: retryEvent.reason,
+			message: ""
+		});
+		runState.lastActivityId = activityId;
+		runState.completedReasoning = void 0;
+		return;
+	}
+	if (event.type === "completeRun") {
+		if (!runState.completionLogged) {
+			const text = event.text ?? "";
+			const activityId = `completion-${event.runId}`;
+			addActivity({
+				type: "complete",
+				id: activityId,
+				expertKey: event.expertKey,
+				runId: event.runId,
+				previousActivityId: runState.lastActivityId,
+				delegatedBy: runState.delegatedBy,
+				reasoning: runState.completedReasoning,
+				text
+			});
+			runState.lastActivityId = activityId;
+			runState.completionLogged = true;
+			runState.isComplete = true;
+			runState.completedReasoning = void 0;
+		}
+		return;
+	}
+	if (event.type === "stopRunByError") {
+		const errorEvent = event;
+		const activityId = `error-${event.id}`;
+		addActivity({
+			type: "error",
+			id: activityId,
+			expertKey: event.expertKey,
+			runId: event.runId,
+			previousActivityId: runState.lastActivityId,
+			delegatedBy: runState.delegatedBy,
+			errorName: errorEvent.error.name,
+			error: errorEvent.error.message,
+			isRetryable: errorEvent.error.isRetryable
+		});
+		runState.lastActivityId = activityId;
+		runState.isComplete = true;
+		runState.completedReasoning = void 0;
+		return;
+	}
+	if (isToolCallsEvent(event)) {
+		for (const toolCall of event.toolCalls) if (!state.tools.has(toolCall.id)) state.tools.set(toolCall.id, {
+			id: toolCall.id,
+			toolCall,
+			logged: false
+		});
+	}
+	if (isStopRunByDelegateEvent(event)) {
+		const reasoning = runState.completedReasoning;
+		const delegations = event.checkpoint.delegateTo ?? [];
+		runState.pendingDelegateCount += delegations.length;
+		const delegateActivities = [];
+		for (const delegation of delegations) {
+			const existingTool = state.tools.get(delegation.toolCallId);
+			if (!existingTool || !existingTool.logged) {
+				if (existingTool) existingTool.logged = true;
+				const activityId = `delegate-${delegation.toolCallId}`;
+				delegateActivities.push({
+					type: "delegate",
+					id: activityId,
+					expertKey: event.expertKey,
+					runId: event.runId,
+					previousActivityId: runState.lastActivityId,
+					delegatedBy: runState.delegatedBy,
+					delegateExpertKey: delegation.expert.key,
+					query: delegation.query,
+					reasoning
+				});
+				runState.lastActivityId = activityId;
+			}
+		}
+		const wrapped = wrapInGroupIfParallel(delegateActivities, reasoning, {
+			expertKey: event.expertKey,
+			runId: event.runId,
+			delegatedBy: runState.delegatedBy
+		});
+		for (const item of wrapped) addActivity(item);
+		runState.completedReasoning = void 0;
+		return;
+	}
+	if (isStopRunByInteractiveToolEvent(event)) {
+		const reasoning = runState.completedReasoning;
+		const pendingToolCalls = event.checkpoint.pendingToolCalls ?? [];
+		const interactiveActivities = [];
+		for (const toolCall of pendingToolCalls) {
+			const existingTool = state.tools.get(toolCall.id);
+			if (!existingTool || !existingTool.logged) {
+				if (existingTool) existingTool.logged = true;
+				const activityId = `interactive-${toolCall.id}`;
+				interactiveActivities.push({
+					type: "interactiveTool",
+					id: activityId,
+					expertKey: event.expertKey,
+					runId: event.runId,
+					previousActivityId: runState.lastActivityId,
+					delegatedBy: runState.delegatedBy,
+					skillName: toolCall.skillName,
+					toolName: toolCall.toolName,
+					args: toolCall.args,
+					reasoning
+				});
+				runState.lastActivityId = activityId;
+			}
+		}
+		const wrapped = wrapInGroupIfParallel(interactiveActivities, reasoning, {
+			expertKey: event.expertKey,
+			runId: event.runId,
+			delegatedBy: runState.delegatedBy
+		});
+		for (const item of wrapped) addActivity(item);
+		runState.completedReasoning = void 0;
+		return;
+	}
+	if (isToolResultsEvent(event)) {
+		const reasoning = runState.completedReasoning;
+		const toolActivities = [];
+		for (const toolResult of event.toolResults) {
+			const tool = state.tools.get(toolResult.id);
+			if (tool && !tool.logged) {
+				const activityId = `action-${tool.id}`;
+				const activity = toolToActivity(tool.toolCall, toolResult, reasoning, {
+					id: activityId,
+					expertKey: event.expertKey,
+					runId: event.runId,
+					previousActivityId: runState.lastActivityId,
+					delegatedBy: runState.delegatedBy
+				});
+				toolActivities.push(activity);
+				runState.lastActivityId = activityId;
+				tool.logged = true;
+			}
+		}
+		if (toolActivities.length > 0) {
+			const wrapped = wrapInGroupIfParallel(toolActivities, reasoning, {
+				expertKey: event.expertKey,
+				runId: event.runId,
+				delegatedBy: runState.delegatedBy
+			});
+			for (const item of wrapped) addActivity(item);
+			runState.completedReasoning = void 0;
+		}
+	}
+}
+
+//#endregion
+//#region src/hooks/use-run.ts
+const STREAMING_EVENT_TYPES = new Set([
+	"startStreamingReasoning",
+	"streamReasoning",
+	"completeStreamingReasoning",
+	"startStreamingRunResult",
+	"streamRunResult",
+	"completeStreamingRunResult"
+]);
+const isStreamingEvent = (event) => "type" in event && "expertKey" in event && STREAMING_EVENT_TYPES.has(event.type);
+function processStreamingEvent(event, prevState) {
+	const { runId, expertKey } = event;
+	switch (event.type) {
+		case "startStreamingReasoning": return {
+			newState: {
+				...prevState,
+				runs: {
+					...prevState.runs,
+					[runId]: {
+						expertKey,
+						reasoning: "",
+						isReasoningActive: true
+					}
+				}
+			},
+			handled: true
+		};
+		case "streamReasoning": return {
+			newState: {
+				...prevState,
+				runs: {
+					...prevState.runs,
+					[runId]: {
+						...prevState.runs[runId],
+						expertKey,
+						reasoning: (prevState.runs[runId]?.reasoning ?? "") + event.delta
+					}
+				}
+			},
+			handled: true
+		};
+		case "completeStreamingReasoning": return {
+			newState: {
+				...prevState,
+				runs: {
+					...prevState.runs,
+					[runId]: {
+						...prevState.runs[runId],
+						expertKey,
+						isReasoningActive: false
+					}
+				}
+			},
+			handled: false
+		};
+		case "startStreamingRunResult": return {
+			newState: {
+				...prevState,
+				runs: {
+					...prevState.runs,
+					[runId]: {
+						expertKey,
+						reasoning: void 0,
+						isReasoningActive: false,
+						runResult: "",
+						isRunResultActive: true
+					}
+				}
+			},
+			handled: true
+		};
+		case "streamRunResult": return {
+			newState: {
+				...prevState,
+				runs: {
+					...prevState.runs,
+					[runId]: {
+						...prevState.runs[runId],
+						expertKey,
+						runResult: (prevState.runs[runId]?.runResult ?? "") + event.delta
+					}
+				}
+			},
+			handled: true
+		};
+		case "completeStreamingRunResult": return {
+			newState: {
+				...prevState,
+				runs: {
+					...prevState.runs,
+					[runId]: {
+						...prevState.runs[runId],
+						expertKey,
+						isRunResultActive: false
+					}
+				}
+			},
+			handled: true
+		};
+		default: return {
+			newState: prevState,
+			handled: false
+		};
+	}
+}
+/**
+* Hook for managing Run state from RunEvent stream.
+*
+* Architecture:
+* - ExpertStateEvent → ActivityOrGroup[] (accumulated, append-only)
+* - StreamingEvent → StreamingState (latest only, for display)
+*
+* IMPORTANT: activities are append-only and never cleared.
+* This is required for compatibility with Ink's <Static> component.
+*/
+function useRun() {
+	const [activities, setActivities] = useState([]);
+	const [streaming, setStreaming] = useState({ runs: {} });
+	const [eventCount, setEventCount] = useState(0);
+	const [isComplete, setIsComplete] = useState(false);
+	const stateRef = useRef(createInitialActivityProcessState());
+	const clearStreaming = useCallback(() => {
+		setStreaming({ runs: {} });
+	}, []);
+	const handleStreamingEvent = useCallback((event) => {
+		let handled = false;
+		setStreaming((prev) => {
+			const result = processStreamingEvent(event, prev);
+			handled = result.handled;
+			return result.newState;
+		});
+		return handled;
+	}, []);
+	const processEvent = useCallback((event) => {
+		const newActivities = [];
+		const addActivity = (activity) => newActivities.push(activity);
+		processRunEventToActivity(stateRef.current, event, addActivity);
+		if (newActivities.length > 0) setActivities((prev) => [...prev, ...newActivities]);
+		setIsComplete(Array.from(stateRef.current.runStates.values()).some((rs) => rs.isComplete && !rs.delegatedBy));
+	}, []);
+	const clearRunStreaming = useCallback((runId) => {
+		setStreaming((prev) => {
+			const { [runId]: _, ...rest } = prev.runs;
+			return { runs: rest };
+		});
+	}, []);
+	return {
+		activities,
+		streaming,
+		isComplete,
+		eventCount,
+		addEvent: useCallback((event) => {
+			if (isStreamingEvent(event)) {
+				if (handleStreamingEvent(event)) {
+					setEventCount((prev) => prev + 1);
+					return;
+				}
+			}
+			if ("type" in event && "runId" in event && (event.type === "completeRun" || event.type === "stopRunByError")) clearRunStreaming(event.runId);
+			processEvent(event);
+			setEventCount((prev) => prev + 1);
+		}, [
+			handleStreamingEvent,
+			clearRunStreaming,
+			processEvent
+		]),
+		appendHistoricalEvents: useCallback((historicalEvents) => {
+			const newActivities = [];
+			const addActivity = (activity) => newActivities.push(activity);
+			for (const event of historicalEvents) processRunEventToActivity(stateRef.current, event, addActivity);
+			if (newActivities.length > 0) setActivities((prev) => [...prev, ...newActivities]);
+			setEventCount((prev) => prev + historicalEvents.length);
+			setIsComplete(Array.from(stateRef.current.runStates.values()).some((rs) => rs.isComplete && !rs.delegatedBy));
+		}, []),
+		clearStreaming
+	};
+}
+
+//#endregion
+//#region src/hooks/use-job-stream.ts
+function useJobStream(options) {
+	const { jobId, connect, enabled = true } = options;
+	const shouldConnect = Boolean(jobId && enabled);
+	const { activities, streaming, addEvent } = useRun();
+	const [isConnected, setIsConnected] = useState(false);
+	const [error, setError] = useState(null);
+	const addEventRef = useRef(addEvent);
+	addEventRef.current = addEvent;
+	const connectRef = useRef(connect);
+	connectRef.current = connect;
+	useEffect(() => {
+		if (!shouldConnect || !jobId) {
+			setIsConnected(false);
+			return;
+		}
+		const controller = new AbortController();
+		async function run() {
+			setError(null);
+			setIsConnected(true);
+			try {
+				await consumeStream(connectRef.current, jobId, controller.signal, (event) => {
+					addEventRef.current(event);
+				});
+			} catch (err) {
+				if (isAbortError(err)) return;
+				setError(err instanceof Error ? err : new Error(String(err)));
+			} finally {
+				setIsConnected(false);
+			}
+		}
+		run();
+		return () => {
+			controller.abort();
+		};
+	}, [shouldConnect, jobId]);
+	return {
+		activities,
+		streaming,
+		latestActivity: useMemo(() => activities.length > 0 ? activities[activities.length - 1] : null, [activities]),
+		isConnected,
+		error
+	};
+}
+
+//#endregion
+//#region src/hooks/use-job-streams.ts
+function useJobStreams(options) {
+	const { jobs, connect } = options;
+	const [states, setStates] = useState(/* @__PURE__ */ new Map());
+	const controllersRef = useRef(/* @__PURE__ */ new Map());
+	const activityStateRef = useRef(/* @__PURE__ */ new Map());
+	const connectRef = useRef(connect);
+	connectRef.current = connect;
+	const connectToJob = useCallback(async (jobId, signal) => {
+		setStates((prev) => {
+			const next = new Map(prev);
+			next.set(jobId, {
+				latestActivity: null,
+				isConnected: true
+			});
+			return next;
+		});
+		let state = activityStateRef.current.get(jobId);
+		if (!state) {
+			state = createInitialActivityProcessState();
+			activityStateRef.current.set(jobId, state);
+		}
+		try {
+			await consumeStream(connectRef.current, jobId, signal, (event) => {
+				let latestActivity = null;
+				processRunEventToActivity(state, event, (activity) => {
+					latestActivity = activity;
+				});
+				if (latestActivity) setStates((prev) => {
+					const next = new Map(prev);
+					next.set(jobId, {
+						latestActivity,
+						isConnected: true
+					});
+					return next;
+				});
+			});
+		} catch (err) {
+			if (isAbortError(err)) return;
+			console.error(`Stream connection failed for job ${jobId}:`, err);
+		} finally {
+			setStates((prev) => {
+				const current = prev.get(jobId);
+				if (!current) return prev;
+				const next = new Map(prev);
+				next.set(jobId, {
+					...current,
+					isConnected: false
+				});
+				return next;
+			});
+		}
+	}, []);
+	useEffect(() => {
+		const enabledIds = new Set(jobs.filter((j) => j.enabled).map((j) => j.id));
+		for (const [jobId, controller] of controllersRef.current) if (!enabledIds.has(jobId)) {
+			controller.abort();
+			controllersRef.current.delete(jobId);
+			activityStateRef.current.delete(jobId);
+			setStates((prev) => {
+				const next = new Map(prev);
+				next.delete(jobId);
+				return next;
+			});
+		}
+		for (const jobId of enabledIds) if (!controllersRef.current.has(jobId)) {
+			const controller = new AbortController();
+			controllersRef.current.set(jobId, controller);
+			connectToJob(jobId, controller.signal);
+		}
+	}, [jobs, connectToJob]);
+	useEffect(() => {
+		return () => {
+			for (const controller of controllersRef.current.values()) controller.abort();
+			controllersRef.current.clear();
+			activityStateRef.current.clear();
+		};
+	}, []);
+	return states;
+}
+
+//#endregion
+//#region src/utils/group-by-run.ts
+/**
+* Extract base properties from ActivityOrGroup for grouping.
+*/
+function getActivityProps(activityOrGroup) {
+	if (activityOrGroup.type === "parallelGroup") {
+		const firstActivity = activityOrGroup.activities[0];
+		return {
+			runId: activityOrGroup.runId,
+			expertKey: activityOrGroup.expertKey,
+			delegatedBy: firstActivity?.delegatedBy
+		};
+	}
+	return activityOrGroup;
+}
+/**
+* Groups activities by their runId while preserving order.
+*
+* This function groups activities so that each run can be displayed in its own
+* visual section (e.g., separate <Static> components in Ink).
+*
+* @param activities - Array of activities or groups to group
+* @returns Array of RunGroup objects, ordered by first appearance
+*/
+function groupActivitiesByRun(activities) {
+	const groupMap = /* @__PURE__ */ new Map();
+	const order = [];
+	for (const activityOrGroup of activities) {
+		const { runId, expertKey, delegatedBy } = getActivityProps(activityOrGroup);
+		if (!groupMap.has(runId)) {
+			groupMap.set(runId, {
+				runId,
+				expertKey,
+				activities: [],
+				delegatedBy
+			});
+			order.push(runId);
+		}
+		groupMap.get(runId).activities.push(activityOrGroup);
+	}
+	return order.map((runId) => groupMap.get(runId));
+}
+
+//#endregion
+export { createInitialActivityProcessState, groupActivitiesByRun, processRunEventToActivity, toolToActivity, useJobStream, useJobStreams, useRun };
 //# sourceMappingURL=index.js.map