@agentick/core 0.0.1

package/dist/jsx/components/timeline.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Timeline Component
+ *
+ * Renders conversation history with optional pending messages.
+ * Supports token budget compaction via maxTokens/strategy props.
+ * Uses React context to provide timeline access to descendants.
+ *
+ * @module agentick/components
+ */
+import { type ReactNode } from "react";
+import type { JSX } from "react";
+import type { COMTimelineEntry } from "../../com/types";
+import type { ExecutionMessage } from "../../engine/execution-types";
+import { type CompactionStrategy, type TokenBudgetInfo } from "./token-budget";
+/**
+ * Render function signature for Timeline component.
+ *
+ * @param history - Executed timeline entries (previous + current)
+ * @param pending - Messages queued for the next tick
+ * @param budget - Token budget info (present when maxTokens is set)
+ */
+export type TimelineRenderFn = (history: COMTimelineEntry[], pending: ExecutionMessage[], budget: TokenBudgetInfo | null) => JSX.Element | (JSX.Element | null)[] | null;
+/**
+ * Context value for Timeline provider.
+ */
+export interface TimelineContextValue {
+    /** All timeline entries (history) */
+    entries: COMTimelineEntry[];
+    /** Pending messages queued for next tick */
+    pending: ExecutionMessage[];
+    /** Number of messages in timeline */
+    messageCount: number;
+    /** Filter entries by role */
+    byRole: (role: "user" | "assistant" | "tool" | "system") => COMTimelineEntry[];
+    /** Token budget info (present when maxTokens is set) */
+    budget: TokenBudgetInfo | null;
+}
+/**
+ * Conversation history options.
+ */
+export interface ConversationHistoryOptions {
+    /** Filter function for entries */
+    filter?: (entry: COMTimelineEntry) => boolean;
+    /** Maximum number of entries to return */
+    limit?: number;
+    /** Only include these roles */
+    roles?: ("user" | "assistant" | "tool" | "system" | "event")[];
+}
+/**
+ * Token budget options for Timeline.
+ */
+export interface TimelineBudgetOptions {
+    /** Maximum tokens for timeline entries. Enables compaction. */
+    maxTokens?: number;
+    /** Compaction strategy (default: "sliding-window") */
+    strategy?: CompactionStrategy;
+    /** Callback when entries are evicted */
+    onEvict?: (entries: COMTimelineEntry[]) => void;
+    /** Guidance string passed to custom compaction functions */
+    guidance?: string;
+    /** Roles that are never evicted (default: ["system"]) */
+    preserveRoles?: Array<"user" | "assistant" | "system" | "tool">;
+    /** Reserve tokens for safety margin (default: 0) */
+    headroom?: number;
+}
+/**
+ * Props for the Timeline component.
+ */
+export interface TimelineProps extends ConversationHistoryOptions, TimelineBudgetOptions {
+    /**
+     * Render prop for custom rendering.
+     * If not provided, renders default message components.
+     */
+    children?: TimelineRenderFn | JSX.Element;
+}
+/**
+ * Renders conversation history from the COM timeline.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Timeline />
+ * ```
+ *
+ * @example With filtering
+ * ```tsx
+ * <Timeline roles={['user', 'assistant']} limit={10} />
+ * ```
+ *
+ * @example With token budget
+ * ```tsx
+ * <Timeline maxTokens={4000} strategy="truncate" />
+ * ```
+ *
+ * @example With render prop
+ * ```tsx
+ * <Timeline maxTokens={8000} headroom={500}>
+ *   {(entries) => entries.map(entry => <Message key={entry.id} entry={entry} />)}
+ * </Timeline>
+ * ```
+ */
+export declare function Timeline(props: TimelineProps): JSX.Element;
+export declare namespace Timeline {
+    var Provider: (props: TimelineProviderProps) => JSX.Element;
+    var Messages: (props: TimelineMessagesProps) => JSX.Element;
+}
+interface TimelineProviderProps extends ConversationHistoryOptions {
+    children: ReactNode;
+    /** Override entries (useful for testing) */
+    entries?: COMTimelineEntry[];
+    /** Override pending messages */
+    pending?: ExecutionMessage[];
+}
+interface TimelineMessagesProps {
+    /** Custom renderer for each entry */
+    renderEntry?: (entry: COMTimelineEntry, index: number) => JSX.Element | null;
+}
+/**
+ * Access timeline context from within Timeline.Provider.
+ *
+ * @example
+ * ```tsx
+ * function MessageCount() {
+ *   const { messageCount, byRole } = useTimelineContext();
+ *   const userMessages = byRole('user');
+ *   return <div>User messages: {userMessages.length} / {messageCount}</div>;
+ * }
+ * ```
+ */
+export declare function useTimelineContext(): TimelineContextValue;
+/**
+ * Access timeline context, returning null if not within provider.
+ * Useful for optional timeline access.
+ */
+export declare function useTimelineContextOptional(): TimelineContextValue | null;
+/**
+ * Get the full conversation history from the COM.
+ *
+ * This hook returns all timeline entries directly from the COM,
+ * without needing to be within a Timeline.Provider.
+ *
+ * @example
+ * ```tsx
+ * function HistoryViewer() {
+ *   const history = useConversationHistory();
+ *   return (
+ *     <div>
+ *       {history.map(entry => (
+ *         <div key={entry.id}>{entry.message.role}: ...</div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useConversationHistory(): COMTimelineEntry[];
+export {};
+//# sourceMappingURL=timeline.d.ts.map

package/dist/jsx/components/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../../src/jsx/components/timeline.tsx"],"names":[],"mappings":"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"}

package/dist/jsx/components/timeline.js

@@ -0,0 +1,357 @@
+/**
+ * Timeline Component
+ *
+ * Renders conversation history with optional pending messages.
+ * Supports token budget compaction via maxTokens/strategy props.
+ * Uses React context to provide timeline access to descendants.
+ *
+ * @module agentick/components
+ */
+import React, { createContext, useContext, useEffect, useMemo, useRef, } from "react";
+import { useTickState } from "../../hooks/context";
+import { compactEntries } from "./token-budget";
+import { Logger } from "@agentick/kernel";
+const log = Logger.for("Timeline");
+// Helper for createElement
+const h = React.createElement;
+// ============================================================================
+// React Context
+// ============================================================================
+const TimelineContext = createContext(null);
+// ============================================================================
+// Default Message Renderer
+// ============================================================================
+/**
+ * Default renderer for a single timeline entry.
+ *
+ * Renders directly to the "entry" intrinsic element to avoid
+ * React trying to render Agentick components that return Agentick elements.
+ */
+function DefaultMessage({ entry, }) {
+    if (!entry.message)
+        return h(React.Fragment, null);
+    const { role, content } = entry.message;
+    // Extract text content
+    const textContent = content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("\n");
+    if (!textContent)
+        return h(React.Fragment, null);
+    // Render the "entry" intrinsic element directly
+    // This avoids going through User/Assistant which return Agentick elements
+    if (role === "user" || role === "assistant" || role === "tool") {
+        return h("entry", {
+            kind: "message",
+            message: {
+                role,
+                content: [{ type: "text", text: textContent }],
+                // Preserve message ID for deduplication in complete()
+                id: entry.message.id,
+            },
+        });
+    }
+    // System and others - skip in default rendering
+    return h(React.Fragment, null);
+}
+/**
+ * Default renderer for a pending (queued) message.
+ *
+ * ExecutionMessage.content contains the actual Message object.
+ */
+function DefaultPendingMessage({ message, }) {
+    // The content is the actual Message object
+    const msg = message.content;
+    if (!msg)
+        return h(React.Fragment, null);
+    const { role, content } = msg;
+    if (!Array.isArray(content))
+        return h(React.Fragment, null);
+    // Extract text content
+    const textContent = content
+        .filter((block) => typeof block === "object" && block !== null && block.type === "text")
+        .map((block) => block.text)
+        .join("\n");
+    if (!textContent)
+        return h(React.Fragment, null);
+    // Render the "entry" intrinsic element
+    // Preserve message ID for deduplication in complete()
+    const msgWithId = msg;
+    return h("entry", {
+        kind: "message",
+        message: {
+            role,
+            content: [{ type: "text", text: textContent }],
+            id: msgWithId.id,
+        },
+    });
+}
+// ============================================================================
+// Helper: Apply filtering to entries
+// ============================================================================
+function applyFilters(entries, options) {
+    let filtered = entries;
+    // Apply role filter
+    if (options.roles && options.roles.length > 0) {
+        const allowedRoles = options.roles;
+        filtered = filtered.filter((entry) => allowedRoles.includes(entry.message.role));
+    }
+    // Apply custom filter
+    if (options.filter) {
+        filtered = filtered.filter(options.filter);
+    }
+    // Apply limit (take from end to get most recent)
+    if (options.limit && options.limit > 0 && filtered.length > options.limit) {
+        filtered = filtered.slice(-options.limit);
+    }
+    return filtered;
+}
+// ============================================================================
+// Timeline Component
+// ============================================================================
+/**
+ * Renders conversation history from the COM timeline.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Timeline />
+ * ```
+ *
+ * @example With filtering
+ * ```tsx
+ * <Timeline roles={['user', 'assistant']} limit={10} />
+ * ```
+ *
+ * @example With token budget
+ * ```tsx
+ * <Timeline maxTokens={4000} strategy="truncate" />
+ * ```
+ *
+ * @example With render prop
+ * ```tsx
+ * <Timeline maxTokens={8000} headroom={500}>
+ *   {(entries) => entries.map(entry => <Message key={entry.id} entry={entry} />)}
+ * </Timeline>
+ * ```
+ */
+export function Timeline(props) {
+    // Get tickState from context (contains previous timeline and queued messages)
+    let tickState = null;
+    try {
+        tickState = useTickState();
+    }
+    catch {
+        // Outside of AgentickProvider - return empty
+    }
+    // Get raw timeline entries, apply filters
+    const filteredEntries = useMemo(() => {
+        if (!tickState?.previous?.timeline) {
+            log.debug({ tick: tickState?.tick, hasPrevious: !!tickState?.previous }, "Timeline: No previous timeline available");
+            return [];
+        }
+        const rawEntries = tickState.previous.timeline;
+        log.debug({
+            tick: tickState.tick,
+            rawCount: rawEntries.length,
+            roles: rawEntries.map((e) => e.message?.role),
+        }, "Timeline: Processing previous timeline");
+        return applyFilters(rawEntries, props);
+    }, [tickState?.previous?.timeline, props.filter, props.limit, props.roles]);
+    // Apply token budget compaction (when maxTokens is set)
+    const { entries, evicted, budgetInfo } = useMemo(() => {
+        if (props.maxTokens == null) {
+            return { entries: filteredEntries, evicted: [], budgetInfo: null };
+        }
+        const result = compactEntries(filteredEntries, {
+            maxTokens: props.maxTokens,
+            strategy: props.strategy,
+            headroom: props.headroom,
+            preserveRoles: props.preserveRoles,
+            guidance: props.guidance,
+        });
+        const info = {
+            maxTokens: props.maxTokens,
+            effectiveBudget: props.maxTokens - (props.headroom ?? 0),
+            currentTokens: result.currentTokens,
+            evictedCount: result.evicted.length,
+            isCompacted: result.evicted.length > 0,
+        };
+        return { entries: result.kept, evicted: result.evicted, budgetInfo: info };
+    }, [
+        filteredEntries,
+        props.maxTokens,
+        props.headroom,
+        props.strategy,
+        props.preserveRoles,
+        props.guidance,
+    ]);
+    // Fire onEvict callback as an effect — not a side effect in memo
+    const onEvictRef = useRef(props.onEvict);
+    onEvictRef.current = props.onEvict;
+    useEffect(() => {
+        if (evicted.length > 0 && onEvictRef.current) {
+            onEvictRef.current(evicted);
+        }
+    }, [evicted]);
+    // Pending messages (queued for this tick)
+    const pending = useMemo(() => {
+        return (tickState?.queuedMessages ?? []);
+    }, [tickState?.queuedMessages]);
+    log.debug({ entriesCount: entries.length, pendingCount: pending.length }, "Timeline: Rendering with entries and pending");
+    // Render based on children type
+    if (props.children !== undefined) {
+        if (typeof props.children === "function") {
+            // Render prop pattern
+            const result = props.children(entries, pending, budgetInfo);
+            return h(React.Fragment, null, result);
+        }
+        // Regular children
+        return h(React.Fragment, null, props.children);
+    }
+    // Default rendering: render history AND pending messages
+    return h(React.Fragment, null, 
+    // Render history entries
+    ...entries.map((entry, index) => h(DefaultMessage, { key: `history-${entry.id ?? index}`, entry })), 
+    // Render pending (queued) messages
+    ...pending.map((message, index) => h(DefaultPendingMessage, { key: `pending-${message.id ?? index}`, message })));
+}
+/**
+ * Provider that exposes timeline context to descendants.
+ *
+ * @example
+ * ```tsx
+ * <Timeline.Provider>
+ *   <MyComponent />
+ * </Timeline.Provider>
+ * ```
+ *
+ * Children can then use:
+ * ```tsx
+ * const { entries, byRole } = useTimelineContext();
+ * ```
+ */
+Timeline.Provider = function TimelineProvider(props) {
+    // Get tickState from context if not overridden
+    let tickState = null;
+    try {
+        tickState = useTickState();
+    }
+    catch {
+        // Outside of AgentickProvider
+    }
+    // Use provided entries or get from tickState.previous.timeline
+    const rawEntries = props.entries ?? (tickState?.previous?.timeline ?? []);
+    const pending = props.pending ?? (tickState?.queuedMessages ?? []);
+    // Apply filters
+    const entries = useMemo(() => {
+        return applyFilters(rawEntries, props);
+    }, [rawEntries, props.filter, props.limit, props.roles]);
+    // Create context value
+    const contextValue = useMemo(() => {
+        return {
+            entries,
+            pending,
+            messageCount: entries.length,
+            byRole: (role) => entries.filter((e) => e.message.role === role),
+            budget: null,
+        };
+    }, [entries, pending]);
+    return h(TimelineContext.Provider, { value: contextValue }, props.children);
+};
+/**
+ * Renders messages from Timeline.Provider context.
+ *
+ * @example
+ * ```tsx
+ * <Timeline.Provider>
+ *   <Timeline.Messages />
+ * </Timeline.Provider>
+ * ```
+ *
+ * @example With custom renderer
+ * ```tsx
+ * <Timeline.Provider>
+ *   <Timeline.Messages
+ *     renderEntry={(entry) => <CustomMessage entry={entry} />}
+ *   />
+ * </Timeline.Provider>
+ * ```
+ */
+Timeline.Messages = function TimelineMessages(props) {
+    const context = useContext(TimelineContext);
+    if (!context) {
+        return h(React.Fragment, null);
+    }
+    const { entries, pending } = context;
+    if (props.renderEntry) {
+        return h(React.Fragment, null, entries.map((entry, index) => props.renderEntry(entry, index)));
+    }
+    // Default rendering: history + pending
+    return h(React.Fragment, null, ...entries.map((entry, index) => h(DefaultMessage, { key: `history-${entry.id ?? index}`, entry })), ...pending.map((message, index) => h(DefaultPendingMessage, { key: `pending-${message.id ?? index}`, message })));
+};
+// ============================================================================
+// useTimelineContext
+// ============================================================================
+/**
+ * Access timeline context from within Timeline.Provider.
+ *
+ * @example
+ * ```tsx
+ * function MessageCount() {
+ *   const { messageCount, byRole } = useTimelineContext();
+ *   const userMessages = byRole('user');
+ *   return <div>User messages: {userMessages.length} / {messageCount}</div>;
+ * }
+ * ```
+ */
+export function useTimelineContext() {
+    const context = useContext(TimelineContext);
+    if (!context) {
+        throw new Error("useTimelineContext must be used within a Timeline.Provider");
+    }
+    return context;
+}
+/**
+ * Access timeline context, returning null if not within provider.
+ * Useful for optional timeline access.
+ */
+export function useTimelineContextOptional() {
+    return useContext(TimelineContext);
+}
+// ============================================================================
+// useConversationHistory
+// ============================================================================
+/**
+ * Get the full conversation history from the COM.
+ *
+ * This hook returns all timeline entries directly from the COM,
+ * without needing to be within a Timeline.Provider.
+ *
+ * @example
+ * ```tsx
+ * function HistoryViewer() {
+ *   const history = useConversationHistory();
+ *   return (
+ *     <div>
+ *       {history.map(entry => (
+ *         <div key={entry.id}>{entry.message.role}: ...</div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useConversationHistory() {
+    // Get tickState from context
+    let tickState = null;
+    try {
+        tickState = useTickState();
+    }
+    catch {
+        // Outside of AgentickProvider
+        return [];
+    }
+    // Return timeline entries from tickState.previous
+    return (tickState?.previous?.timeline ?? []);
+}
+//# sourceMappingURL=timeline.js.map

package/dist/jsx/components/timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.js","sourceRoot":"","sources":["../../../src/jsx/components/timeline.tsx"],"names":[],"mappings":"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"}

package/dist/jsx/components/token-budget.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Token Budget — Compaction utilities for timeline entries.
+ *
+ * Pure functions and types for managing token budgets. No components,
+ * no contexts, no hooks. Used internally by Timeline when budget
+ * props (maxTokens, strategy, etc.) are provided.
+ *
+ * Uses `.tokens` field from token estimation when available,
+ * falls back to char/4 heuristic.
+ */
+import type { COMTimelineEntry } from "../../com/types";
+/**
+ * Compaction strategy for handling token budget overflow.
+ *
+ * - `"none"`: No compaction, entries pass through unchanged
+ * - `"truncate"`: Keep newest entries that fit within budget
+ * - `"sliding-window"`: Preserve specific roles, then fill remaining budget with newest entries
+ * - Custom function: Full control over compaction logic
+ */
+export type CompactionStrategy = "none" | "truncate" | "sliding-window" | CompactionFunction;
+/**
+ * Custom compaction function signature.
+ */
+export type CompactionFunction = (entries: COMTimelineEntry[], budget: {
+    maxTokens: number;
+    currentTokens: number;
+}, guidance?: string) => CompactionResult;
+/**
+ * Result from a compaction operation.
+ */
+export interface CompactionResult {
+    kept: COMTimelineEntry[];
+    evicted: COMTimelineEntry[];
+}
+/**
+ * Token budget info exposed via TimelineContextValue.
+ */
+export interface TokenBudgetInfo {
+    /** Configured max tokens */
+    maxTokens: number;
+    /** Effective budget after headroom */
+    effectiveBudget: number;
+    /** Current token count of kept entries */
+    currentTokens: number;
+    /** Number of entries evicted */
+    evictedCount: number;
+    /** Whether compaction was applied */
+    isCompacted: boolean;
+}
+/** Get token count for an entry. Uses .tokens field if available, falls back to char/4. */
+export declare function getEntryTokens(entry: COMTimelineEntry): number;
+export interface CompactOptions {
+    maxTokens: number;
+    strategy?: CompactionStrategy;
+    headroom?: number;
+    preserveRoles?: string[];
+    guidance?: string;
+}
+export interface CompactResult {
+    kept: COMTimelineEntry[];
+    evicted: COMTimelineEntry[];
+    currentTokens: number;
+}
+/**
+ * Apply token budget compaction to a set of entries.
+ *
+ * Pure function — no side effects, no React, no hooks.
+ */
+export declare function compactEntries(entries: COMTimelineEntry[], options: CompactOptions): CompactResult;
+//# sourceMappingURL=token-budget.d.ts.map

package/dist/jsx/components/token-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.d.ts","sourceRoot":"","sources":["../../../src/jsx/components/token-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAMxD;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;AAE7F;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,gBAAgB,EAAE,EAC3B,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EACpD,QAAQ,CAAC,EAAE,MAAM,KACd,gBAAgB,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,WAAW,EAAE,OAAO,CAAC;CACtB;AAMD,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAsB9D;AA+ED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,gBAAgB,EAAE,EAC3B,OAAO,EAAE,cAAc,GACtB,aAAa,CAuCf"}