@agentick/core 0.0.1

package/dist/state/hooks.d.ts

@@ -0,0 +1,798 @@
+/**
+ * V2 Hooks Implementation
+ *
+ * React-inspired hooks for function components in the tick-based agent model.
+ * Key difference from React: async-first, effects can be async.
+ *
+ * Rules of Hooks:
+ * 1. Only call hooks at the top level of a function component
+ * 2. Only call hooks from function components or custom hooks
+ * 3. Call hooks in the same order every render
+ */
+import type { FiberNode, RenderContext, StateHookResult, ReducerHookResult, RefObject, AsyncResult, EffectCallback } from "../compiler/types";
+import { type Signal, type ComputedSignal, type ReadonlySignal } from "./signal";
+import type { COM } from "../com/object-model";
+import type { COMTimelineEntry } from "../com/types";
+import type { TickState } from "../component/component";
+import type { CompiledStructure } from "../compiler/types";
+import type { ExecutionMessage } from "../engine/execution-types";
+/**
+ * Get current render context. Throws if called outside render.
+ */
+export declare function getCurrentContext(): RenderContext;
+/**
+ * Set render context (called by compiler).
+ */
+export declare function setRenderContext(ctx: RenderContext | null): void;
+/**
+ * Get current fiber (for advanced use).
+ */
+export declare function getCurrentFiber(): FiberNode | null;
+/**
+ * Get the COM (Context Object Model) for the current render.
+ *
+ * Use this instead of receiving COM as a component parameter.
+ * This makes components have standard React-like signatures: `(props) => JSX.Element`
+ *
+ * @example
+ * ```tsx
+ * // Before (legacy pattern with magic args):
+ * const MyComponent = (props, com, state) => { ... };
+ *
+ * // After (recommended hook pattern):
+ * const MyComponent = (props) => {
+ *   const com = useCom();
+ *   const state = useTickState();
+ *   // ...
+ * };
+ * ```
+ */
+export declare function useCom(): COM;
+/**
+ * Get the TickState for the current render.
+ *
+ * TickState contains:
+ * - `tick`: Current tick number (1-indexed)
+ * - `previous`: COMInput from previous tick (conversation history)
+ * - `current`: COMOutput from current tick (model response)
+ * - `stop(reason)`: Function to stop execution
+ * - `queuedMessages`: Messages received during execution
+ *
+ * @example
+ * ```tsx
+ * const MyComponent = (props) => {
+ *   const state = useTickState();
+ *   console.log(`Tick ${state.tick}`);
+ *   // Access previous conversation via state.previous?.timeline
+ * };
+ * ```
+ */
+export declare function useTickState(): TickState;
+/**
+ * useState - Local component state.
+ *
+ * State persists across renders via fiber storage.
+ *
+ * @example
+ * ```tsx
+ * // Old (deprecated):
+ * const [count, setCount] = useState(0);
+ *
+ * // New (recommended):
+ * const count = useSignal(0);
+ * count.set(10) or count.update(n => n + 1)
+ * ```
+ */
+export declare function useState<S>(initialState: S | (() => S)): StateHookResult<S>;
+/**
+ * useReducer - State with reducer pattern.
+ */
+export declare function useReducer<S, A>(reducer: (state: S, action: A) => S, initialArg: S, init?: (arg: S) => S): ReducerHookResult<S, A>;
+/**
+ * useSignal - Signal-based state in function components.
+ *
+ * Provides full signal API (not just [value, setter]).
+ * Automatically triggers recompiles when the signal is updated (like useState).
+ *
+ * @example
+ * ```tsx
+ * function Counter() {
+ *   const count = useSignal(0);
+ *   return <Text>Count: {count()}</Text>;
+ * }
+ * ```
+ */
+export declare function useSignal<T>(initialValue: T): Signal<T>;
+/**
+ * useComState - COM-bound shared state.
+ *
+ * Returns a signal bound to COM state. State is shared across all components
+ * and persisted. Changes automatically trigger recompilation.
+ *
+ * @example
+ * ```tsx
+ * function Timeline() {
+ *   const messages = useComState('timeline', []);
+ *   return <Timeline>{messages().map(...)}</Timeline>;
+ * }
+ * ```
+ */
+export declare function useComState<T>(key: string, initialValue: T): Signal<T>;
+/**
+ * useWatch - Read-only COM state observation.
+ * Returns a ReadonlySignal for reactive access to the watched state.
+ *
+ * @example
+ * ```tsx
+ * function StatusDisplay() {
+ *   const status = useWatch('agentStatus', 'idle');
+ *   return <Text>Status: {status()}</Text>;
+ * }
+ * ```
+ */
+export declare function useWatch<T>(key: string, defaultValue?: T): ReadonlySignal<T | undefined>;
+/**
+ * useInput - Reactive prop access with default value.
+ */
+export declare function useInput<T>(propKey: string, defaultValue?: T): T | undefined;
+/**
+ * useEffect - Side effect after commit.
+ *
+ * Unlike React, callback CAN be async.
+ * Signals/computed values in deps array are automatically unwrapped.
+ *
+ * During hydration:
+ * - Mount effects (deps = []) are skipped (state is restored, not fresh)
+ * - Effects with deps still run (deps might have changed since snapshot)
+ *
+ * @example
+ * ```tsx
+ * function Logger() {
+ *   const message = useComState('message', '');
+ *
+ *   useEffect(async () => {
+ *     await logToServer(message());  // Read signal value
+ *     return () => console.log('cleanup');
+ *   }, [message]);  // Signal auto-tracked by value
+ * }
+ * ```
+ */
+export declare function useEffect(create: EffectCallback, deps?: unknown[]): void;
+/**
+ * useInit - Component initialization that runs once on mount.
+ * Can be async and should be awaited if it returns a Promise.
+ * Runs DURING render, blocking until complete.
+ *
+ * Use for: loading initial data, setting up state before first render
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const data = useComState('data', []);
+ *
+ *   await useInit(async (com, state) => {
+ *     const initialData = await loadData();
+ *     data.set(initialData);
+ *   });
+ *
+ *   return <Section>{data().map(...)}</Section>;
+ * }
+ * ```
+ */
+export declare function useInit(callback: (com: COM, state: TickState) => void | Promise<void>): Promise<void>;
+/**
+ * useOnMount - Run once when component mounts as a side effect.
+ * Runs AFTER render (as an effect), does not block rendering.
+ * Use for non-critical side effects like logging, analytics.
+ *
+ * For blocking initialization, use `useInit` instead.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   useOnMount((com) => {
+ *     log.info('Component mounted');
+ *   });
+ *   return <Text>Hello</Text>;
+ * }
+ * ```
+ */
+export declare function useOnMount(callback: (com: COM) => void | Promise<void>): void;
+/**
+ * useOnUnmount - Run once when component unmounts.
+ */
+export declare function useOnUnmount(callback: (com: COM) => void | Promise<void>): void;
+/**
+ * useTickStart - Run at start of each tick, before render.
+ *
+ * @deprecated Use `useOnTickStart` instead for consistent naming convention.
+ */
+export declare function useTickStart(callback: (com: COM, state: TickState) => void | Promise<void>): void;
+/**
+ * useTickEnd - Run at end of each tick, after model execution.
+ *
+ * @deprecated Use `useOnTickEnd` instead for consistent naming convention.
+ */
+export declare function useTickEnd(callback: (com: COM, state: TickState) => void | Promise<void>): void;
+/**
+ * useAfterCompile - Run after compile, can request recompile.
+ *
+ * @deprecated Use `useOnAfterCompile` instead for consistent naming convention.
+ */
+export declare function useAfterCompile(callback: (com: COM, compiled: CompiledStructure, state: TickState) => void): void;
+/**
+ * useOnMessage - Handle execution messages.
+ *
+ * Called immediately when messages are sent to the running execution via:
+ * - RuntimeSession.sendMessage() - Direct programmatic injection
+ * - ExecutionHandle.send() - Via handle reference
+ * - Channel events with type='message' - From client
+ *
+ * Messages are processed immediately when they arrive, not at tick boundaries.
+ * Use com.abort() to interrupt execution if needed, or update state for the next tick.
+ * Messages are also available in TickState.queuedMessages during render.
+ *
+ * @example
+ * ```tsx
+ * function InteractiveAgent() {
+ *   const feedback = useComState('userFeedback', []);
+ *
+ *   useOnMessage((com, message, state) => {
+ *     if (message.type === 'stop') {
+ *       com.abort('User requested stop');
+ *     } else if (message.type === 'feedback') {
+ *       feedback.update(f => [...f, message.content]);
+ *     }
+ *   });
+ *
+ *   return <Section>{feedback().map(f => <Paragraph>{f}</Paragraph>)}</Section>;
+ * }
+ * ```
+ */
+export declare function useOnMessage(callback: (com: COM, message: ExecutionMessage, state: TickState) => void | Promise<void>): void;
+/**
+ * useOnTickStart - Run at start of each tick, before render.
+ *
+ * This is the canonical hook for tick-start lifecycle.
+ * Alias: useTickStart (deprecated, prefer useOnTickStart)
+ *
+ * @example
+ * ```tsx
+ * function MyAgent() {
+ *   useOnTickStart((com, state) => {
+ *     console.log(`Starting tick ${state.tick}`);
+ *   });
+ *   return <System>You are helpful.</System>;
+ * }
+ * ```
+ */
+export declare function useOnTickStart(callback: (com: COM, state: TickState) => void | Promise<void>): void;
+/**
+ * useOnAfterRender - Run after render/reconciliation, before compile.
+ *
+ * Use this to inspect or modify state after all components have rendered
+ * but before the context is compiled and sent to the model.
+ *
+ * @example
+ * ```tsx
+ * function MyAgent() {
+ *   useOnAfterRender((com, state) => {
+ *     console.log('Components rendered, about to compile');
+ *   });
+ *   return <System>You are helpful.</System>;
+ * }
+ * ```
+ */
+export declare function useOnAfterRender(callback: (com: COM, state: TickState) => void | Promise<void>): void;
+/**
+ * useOnAfterCompile - Run after compile, before model call.
+ *
+ * Use this to transform the compiled structure before it's sent to the model.
+ * Can request recompile if needed.
+ *
+ * This is the canonical hook for after-compile lifecycle.
+ * Alias: useAfterCompile (deprecated, prefer useOnAfterCompile)
+ *
+ * @example
+ * ```tsx
+ * function MyAgent() {
+ *   useOnAfterCompile((com, compiled, state) => {
+ *     // Inspect or modify compiled structure
+ *     if (compiled.tokenCount > 10000) {
+ *       // Request summarization
+ *     }
+ *   });
+ *   return <System>You are helpful.</System>;
+ * }
+ * ```
+ */
+export declare function useOnAfterCompile(callback: (com: COM, compiled: CompiledStructure, state: TickState) => void): void;
+/**
+ * useOnTickEnd - Run at end of each tick, after model execution.
+ *
+ * Use this to process model response, decide on continuation, or clean up.
+ *
+ * This is the canonical hook for tick-end lifecycle.
+ * Alias: useTickEnd (deprecated, prefer useOnTickEnd)
+ *
+ * @example
+ * ```tsx
+ * function MyAgent() {
+ *   useOnTickEnd((com, state) => {
+ *     console.log(`Tick ${state.tick} complete`);
+ *     if (state.response?.stopReason === 'stop') {
+ *       com.complete();
+ *     }
+ *   });
+ *   return <System>You are helpful.</System>;
+ * }
+ * ```
+ */
+export declare function useOnTickEnd(callback: (com: COM, state: TickState) => void | Promise<void>): void;
+/**
+ * useOnComplete - Run when session completes (all ticks done).
+ *
+ * This hook runs once when the session finishes execution, whether through:
+ * - Natural completion (shouldContinue returns false)
+ * - Explicit com.complete() call
+ * - Error or abort
+ *
+ * Use this for cleanup, final logging, or teardown logic.
+ *
+ * @example
+ * ```tsx
+ * function MyAgent() {
+ *   useOnComplete((com, state) => {
+ *     console.log(`Session complete after ${state.tick} ticks`);
+ *     // Cleanup resources
+ *   });
+ *   return <System>You are helpful.</System>;
+ * }
+ * ```
+ */
+export declare function useOnComplete(callback: (com: COM, state: TickState) => void | Promise<void>): void;
+/**
+ * useAsync - Async data fetching.
+ *
+ * Unlike React (which needs Suspense), we just track loading state.
+ * The tick can wait for async work to complete.
+ *
+ * @example
+ * ```tsx
+ * function UserProfile({ userId }) {
+ *   const { data: user, loading, error } = useAsync(
+ *     () => fetchUser(userId),
+ *     [userId]
+ *   );
+ *
+ *   if (loading) return null;
+ *   if (error) return <Text>Error: {error.message}</Text>;
+ *
+ *   return <Text>User: {user.name}</Text>;
+ * }
+ * ```
+ */
+export declare function useAsync<T>(asyncFn: () => Promise<T>, deps: unknown[]): AsyncResult<T>;
+/**
+ * useMemo - Memoize expensive computation.
+ */
+export declare function useMemo<T>(factory: () => T, deps: unknown[]): T;
+/**
+ * useComputed - Create a reactive computed signal that persists across renders.
+ *
+ * Unlike useMemo which returns a plain value, useComputed returns a ComputedSignal
+ * that automatically tracks dependencies and updates when they change.
+ * The computed signal is disposed and recreated only when deps change.
+ *
+ * @example
+ * ```typescript
+ * const timeline = useComState('timeline', []);
+ * const recentMessages = useComputed(() => timeline().slice(-10), []);
+ *
+ * // Read the computed value
+ * const messages = recentMessages();  // or recentMessages.value
+ * ```
+ */
+export declare function useComputed<T>(computation: () => T, deps?: unknown[]): ComputedSignal<T>;
+/**
+ * useCallback - Memoize callback function.
+ */
+export declare function useCallback<T extends (...args: unknown[]) => unknown>(callback: T, deps: unknown[]): T;
+/**
+ * useRef - Mutable ref that persists across renders.
+ */
+export declare function useRef<T>(initialValue: T): RefObject<T>;
+/**
+ * useCOMRef - Get component ref from COM.
+ */
+export declare function useCOMRef<T>(refName: string): T | undefined;
+/**
+ * usePrevious - Track previous value.
+ */
+export declare function usePrevious<T>(value: T): T | undefined;
+/**
+ * useToggle - Boolean toggle state.
+ */
+export declare function useToggle(initial?: boolean): [boolean, () => void];
+/**
+ * useCounter - Numeric counter.
+ */
+export declare function useCounter(initial?: number): {
+    count: number;
+    increment: () => void;
+    decrement: () => void;
+    set: (n: number) => void;
+    reset: () => void;
+};
+/**
+ * useAbortSignal - Get abort signal for current execution.
+ */
+export declare function useAbortSignal(): AbortSignal | undefined;
+/**
+ * useDebugValue - Display value in devtools (no-op in production).
+ */
+export declare function useDebugValue<T>(value: T, formatter?: (value: T) => unknown): void;
+/**
+ * Result of useTick() hook.
+ */
+export interface UseTickResult {
+    /** Request a tick to be scheduled */
+    requestTick(): void;
+    /** Cancel a pending tick request */
+    cancelTick(): void;
+    /** Current tick status: 'idle' | 'running' | 'pending' */
+    tickStatus: "idle" | "running" | "pending";
+    /** Total number of ticks executed */
+    tickCount: number;
+}
+/**
+ * useTick - Control tick execution from within a component.
+ *
+ * This hook provides components with the ability to:
+ * - Request a new tick (e.g., when enough messages have accumulated)
+ * - Cancel a pending tick request
+ * - Check the current tick status
+ * - Get the total tick count
+ *
+ * @example
+ * ```tsx
+ * function BatchProcessor() {
+ *   const { requestTick, tickStatus, tickCount } = useTick();
+ *   const queue = useComState('queue', []);
+ *
+ *   useEffect(() => {
+ *     // Request tick when queue has 10 items and we're idle
+ *     if (queue().length >= 10 && tickStatus === 'idle') {
+ *       requestTick();
+ *     }
+ *   }, [queue().length, tickStatus]);
+ *
+ *   return <Section>Tick {tickCount}: {queue().length} items</Section>;
+ * }
+ * ```
+ */
+export declare function useTick(): UseTickResult;
+import type { Channel, ChannelEvent } from "../core/channel";
+/**
+ * Result of useChannel() hook.
+ * Provides access to a named channel for pub/sub communication.
+ */
+export interface UseChannelResult {
+    /**
+     * The underlying Channel instance.
+     * May be undefined if channels are not configured.
+     */
+    channel: Channel | undefined;
+    /**
+     * Subscribe to channel events.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * ```tsx
+     * const { subscribe } = useChannel('updates');
+     * useEffect(() => subscribe(handleEvent), []);
+     * ```
+     */
+    subscribe: (handler: (event: ChannelEvent) => void) => () => void;
+    /**
+     * Publish an event to the channel.
+     *
+     * @example
+     * ```tsx
+     * const { publish } = useChannel('events');
+     * publish({ type: 'status', payload: { ready: true } });
+     * ```
+     */
+    publish: (event: Omit<ChannelEvent, "channel">) => void;
+    /**
+     * Wait for a response to a specific request.
+     *
+     * @example
+     * ```tsx
+     * const { waitForResponse, publish } = useChannel('confirmations');
+     * publish({ type: 'request', id: 'confirm-1', payload: { action: 'delete' } });
+     * const response = await waitForResponse('confirm-1', 30000);
+     * ```
+     */
+    waitForResponse: (requestId: string, timeoutMs?: number) => Promise<ChannelEvent>;
+    /**
+     * Whether the channel is available.
+     * False if channel service is not configured.
+     */
+    available: boolean;
+}
+/**
+ * useChannel - Access a named channel for pub/sub communication.
+ *
+ * Channels enable real-time bidirectional communication between components
+ * and external code (UI, other services, etc.).
+ *
+ * Use cases:
+ * - User input during model execution (e.g., stop button, feedback)
+ * - Progress updates to UI
+ * - Tool confirmation dialogs
+ * - Live data streaming to/from external systems
+ *
+ * @param name - Channel name (e.g., 'progress', 'user-input', 'tool:confirm')
+ * @returns Channel access object with subscribe, publish, and waitForResponse
+ *
+ * @example Basic subscription
+ * ```tsx
+ * function ProgressDisplay() {
+ *   const [progress, setProgress] = useState(0);
+ *   const { subscribe, available } = useChannel('progress');
+ *
+ *   useEffect(() => {
+ *     if (!available) return;
+ *     return subscribe((event) => {
+ *       if (event.type === 'update') {
+ *         setProgress(event.payload.percent);
+ *       }
+ *     });
+ *   }, [available]);
+ *
+ *   return <Section>Progress: {progress}%</Section>;
+ * }
+ * ```
+ *
+ * @example Request/Response pattern
+ * ```tsx
+ * function ConfirmationHandler() {
+ *   const { publish, waitForResponse, available } = useChannel('confirmations');
+ *
+ *   const confirmAction = async (action: string) => {
+ *     if (!available) throw new Error('Channels not available');
+ *
+ *     const requestId = crypto.randomUUID();
+ *     publish({ type: 'request', id: requestId, payload: { action } });
+ *     const response = await waitForResponse(requestId, 30000);
+ *     return response.payload.confirmed;
+ *   };
+ *
+ *   // ...
+ * }
+ * ```
+ *
+ * @example Publishing events
+ * ```tsx
+ * function StatusReporter() {
+ *   const { publish } = useChannel('status');
+ *
+ *   useTickEnd(() => {
+ *     publish({ type: 'tick-complete', payload: { timestamp: Date.now() } });
+ *   });
+ *
+ *   return null;
+ * }
+ * ```
+ */
+export declare function useChannel(name: string): UseChannelResult;
+/**
+ * useChannelSubscription - Subscribe to channel events with automatic cleanup.
+ *
+ * This is a convenience hook that combines useChannel with useEffect for
+ * the common pattern of subscribing to a channel and cleaning up on unmount.
+ *
+ * @param name - Channel name
+ * @param handler - Event handler function
+ * @param deps - Dependencies array (handler is only updated when deps change)
+ *
+ * @example
+ * ```tsx
+ * function NotificationListener() {
+ *   const [notifications, setNotifications] = useState<string[]>([]);
+ *
+ *   useChannelSubscription('notifications', (event) => {
+ *     if (event.type === 'new') {
+ *       setNotifications(n => [...n, event.payload.message]);
+ *     }
+ *   }, []);
+ *
+ *   return <Section>{notifications.map(n => <Text>{n}</Text>)}</Section>;
+ * }
+ * ```
+ */
+export declare function useChannelSubscription(name: string, handler: (event: ChannelEvent) => void, deps?: unknown[]): void;
+/**
+ * Options for filtering and limiting conversation history.
+ */
+export interface ConversationHistoryOptions {
+    /**
+     * Filter function to include/exclude entries.
+     * @example Filter out system messages: (e) => e.message?.role !== 'system'
+     */
+    filter?: (entry: COMTimelineEntry) => boolean;
+    /**
+     * Maximum number of entries to return (from the end).
+     * @example Last 10 messages: { limit: 10 }
+     */
+    limit?: number;
+    /**
+     * Include only entries from specific roles.
+     * @example Only user/assistant: { roles: ['user', 'assistant'] }
+     */
+    roles?: Array<"user" | "assistant" | "tool" | "system">;
+}
+/**
+ * Get the full conversation history across all ticks.
+ *
+ * Combines `state.previous.timeline` (history) with `state.current.timeline`
+ * (current tick) into a single array.
+ *
+ * This is a utility hook that extracts data from TickState - it doesn't use the
+ * fiber system and can be called anywhere you have access to TickState.
+ *
+ * @param state - The TickState from component context
+ * @param options - Optional filtering and limiting
+ * @returns Array of timeline entries
+ *
+ * @example Basic usage
+ * ```tsx
+ * const ChatAgent = ({ message }: Props) => {
+ *   const history = useConversationHistory();
+ *
+ *   return (
+ *     <>
+ *       <Model model={claude} />
+ *       <System>You are helpful.</System>
+ *       {history.map((entry, i) => (
+ *         <Message key={i} {...entry.message} />
+ *       ))}
+ *       <User>{message}</User>
+ *     </>
+ *   );
+ * };
+ * ```
+ *
+ * @example With options
+ * ```tsx
+ * const history = useConversationHistory({
+ *   roles: ['user', 'assistant'],  // Exclude tool messages
+ *   limit: 10,                      // Last 10 messages
+ * });
+ * ```
+ */
+export declare function useConversationHistory(options?: ConversationHistoryOptions): COMTimelineEntry[];
+/**
+ * Get just the messages from conversation history (convenience wrapper).
+ *
+ * @param options - Optional filtering and limiting
+ * @returns Array of messages (excluding entries without messages)
+ */
+export declare function useMessages(options?: ConversationHistoryOptions): Array<COMTimelineEntry["message"]>;
+/**
+ * Get message count from conversation history.
+ *
+ * @returns Number of messages in history
+ */
+export declare function useMessageCount(): number;
+/**
+ * Get messages queued for the next tick.
+ *
+ * Messages can be queued via:
+ * - `session.queue.exec(msg)` - Queue a message for later processing
+ * - `session.interrupt(msg)` - Interrupt and queue a message
+ * - `RuntimeSession.sendMessage(msg)` - Direct programmatic injection
+ *
+ * Queued messages are available during render and can be used to show
+ * pending messages in the UI or to process them in the current tick.
+ *
+ * @returns Array of queued execution messages
+ *
+ * @example Show pending messages
+ * ```tsx
+ * const ChatWithPending = () => {
+ *   const history = useConversationHistory();
+ *   const pending = useQueuedMessages();
+ *
+ *   return (
+ *     <>
+ *       {history.map((entry, i) => (
+ *         <Message key={i} {...entry.message} />
+ *       ))}
+ *       {pending.length > 0 && (
+ *         <System>Processing {pending.length} pending message(s)...</System>
+ *       )}
+ *     </>
+ *   );
+ * };
+ * ```
+ *
+ * @example Process pending messages
+ * ```tsx
+ * const Agent = () => {
+ *   const pending = useQueuedMessages();
+ *
+ *   // Access the first pending message if any
+ *   const firstPending = pending[0];
+ *   if (firstPending?.type === 'interrupt') {
+ *     return <System>Handling interrupt: {firstPending.content}</System>;
+ *   }
+ *
+ *   return <AssistantMessage />;
+ * };
+ * ```
+ */
+export declare function useQueuedMessages(): ExecutionMessage[];
+/**
+ * Inject historical timeline entries into the conversation.
+ *
+ * Use this to load an existing conversation when the component mounts.
+ * The entries are injected once (on first render) and then available via
+ * `useConversationHistory()` and `<Timeline />`.
+ *
+ * This hook only injects on the first render. On subsequent renders (tick 2+),
+ * the timeline naturally includes all entries via `TickState.previous.timeline`.
+ *
+ * @param entries - Timeline entries to inject, or a function that returns them
+ * @param deps - Dependency array (like useEffect). If omitted, injects once on mount.
+ *
+ * @example Basic usage with static entries
+ * ```tsx
+ * const ChatAgent = ({ conversationHistory }: Props) => {
+ *   useInjectHistory(conversationHistory);
+ *   return <Timeline />;
+ * };
+ * ```
+ *
+ * @example Async loading in useInit
+ * ```tsx
+ * const ChatAgent = ({ conversationId }: Props) => {
+ *   const [loaded, setLoaded] = useState(false);
+ *
+ *   await useInit(async () => {
+ *     const conversation = await loadConversation(conversationId);
+ *     injectHistory(conversation.entries);  // Use standalone function
+ *     setLoaded(true);
+ *   });
+ *
+ *   if (!loaded) return null;
+ *   return <Timeline />;
+ * };
+ * ```
+ */
+export declare function useInjectHistory(entries: COMTimelineEntry[] | (() => COMTimelineEntry[]), deps?: unknown[]): void;
+/**
+ * Standalone function to inject history (for use in useInit or async contexts).
+ *
+ * Unlike the hook, this can be called anywhere you have access to COM.
+ *
+ * @param com - The COM instance
+ * @param entries - Timeline entries to inject
+ *
+ * @example
+ * ```tsx
+ * const ChatAgent = ({ conversationId }: Props) => {
+ *   const com = useCom();
+ *
+ *   await useInit(async () => {
+ *     const conversation = await loadConversation(conversationId);
+ *     injectHistory(com, conversation.entries);
+ *   });
+ *
+ *   return <Timeline />;
+ * };
+ * ```
+ */
+export declare function injectHistory(com: COM, entries: COMTimelineEntry[]): void;
+//# sourceMappingURL=hooks.d.ts.map