@agentick/core 0.0.1

package/dist/hibernation/index.js

@@ -0,0 +1,127 @@
+/**
+ * V2 Session Hibernation
+ *
+ * Serialize and restore session state for persistence.
+ *
+ * Unlike React's hydration (which is about attaching to pre-rendered DOM),
+ * this is about serializing our state and restoring it later.
+ *
+ * Key insight: We don't need to serialize React's fiber tree. We serialize
+ * OUR state, and React rebuilds its tree from scratch on restore. Since our
+ * hooks (useData, etc.) read from our caches, the render produces the same
+ * output as before hibernation.
+ */
+/**
+ * Create a serializable snapshot of the session state.
+ *
+ * @example
+ * ```typescript
+ * const snapshot = hibernate(compiler, {
+ *   sessionId: session.id,
+ *   tick: session.currentTick,
+ *   timeline: session.timeline,
+ *   comState: session.ctx.state,
+ * });
+ *
+ * // Store snapshot
+ * await db.sessions.save(session.id, JSON.stringify(snapshot));
+ * ```
+ */
+export function hibernate(compiler, state, options = {}) {
+    return {
+        version: 1,
+        sessionId: state.sessionId,
+        tick: state.tick,
+        timeline: state.timeline.map((entry) => ({
+            id: entry.id,
+            role: entry.role,
+            content: entry.content,
+            createdAt: entry.createdAt.toISOString(),
+        })),
+        comState: Object.fromEntries(state.comState),
+        dataCache: compiler.getSerializableDataCache(),
+        createdAt: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+/**
+ * Restore session state from a snapshot.
+ *
+ * This restores our caches and returns the state to apply to a session.
+ * The session can then render and React will produce the same output
+ * because our hooks read from the restored caches.
+ *
+ * @example
+ * ```typescript
+ * // Load snapshot from storage
+ * const json = await db.sessions.get(sessionId);
+ * const snapshot = JSON.parse(json) as SessionSnapshot;
+ *
+ * // Create compiler first
+ * const compiler = new FiberCompiler(ctx);
+ *
+ * // Hydrate - restores data cache into compiler
+ * const state = hydrate(compiler, snapshot);
+ *
+ * // Now create/configure session with restored state
+ * session.timeline = state.timeline;
+ * session.currentTick = state.tick;
+ * // etc.
+ * ```
+ */
+export function hydrate(compiler, snapshot) {
+    // Validate version
+    if (snapshot.version !== 1) {
+        throw new Error(`Unsupported snapshot version: ${snapshot.version}`);
+    }
+    // Restore data cache into the compiler's runtime store
+    compiler.setDataCache(snapshot.dataCache);
+    // Convert timeline dates back
+    const timeline = snapshot.timeline.map((entry) => ({
+        id: entry.id,
+        role: entry.role,
+        content: entry.content,
+        createdAt: new Date(entry.createdAt),
+    }));
+    // Convert comState back to Map
+    const comState = new Map(Object.entries(snapshot.comState));
+    return {
+        sessionId: snapshot.sessionId,
+        tick: snapshot.tick,
+        timeline,
+        comState,
+        metadata: snapshot.metadata,
+        snapshotCreatedAt: new Date(snapshot.createdAt),
+    };
+}
+// ============================================================
+// Utilities
+// ============================================================
+/**
+ * Check if a snapshot is valid.
+ */
+export function isValidSnapshot(obj) {
+    if (!obj || typeof obj !== "object")
+        return false;
+    const s = obj;
+    return (s.version === 1 &&
+        typeof s.sessionId === "string" &&
+        typeof s.tick === "number" &&
+        Array.isArray(s.timeline) &&
+        typeof s.comState === "object" &&
+        typeof s.dataCache === "object" &&
+        typeof s.createdAt === "string");
+}
+/**
+ * Get snapshot age in milliseconds.
+ */
+export function getSnapshotAge(snapshot) {
+    return Date.now() - new Date(snapshot.createdAt).getTime();
+}
+/**
+ * Create a deep clone of a snapshot (for testing/debugging).
+ */
+export function cloneSnapshot(snapshot) {
+    return JSON.parse(JSON.stringify(snapshot));
+}
+//# sourceMappingURL=index.js.map

package/dist/hibernation/index.js.map

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

package/dist/hooks/base-hook-registry.d.ts

@@ -0,0 +1,41 @@
+import { HookRegistry } from "./hook-registry";
+/**
+ * Base class for hook registries that provides common overloaded register methods.
+ * Reduces code duplication across ModelHookRegistry, ToolHookRegistry, etc.
+ */
+export declare abstract class BaseHookRegistry<THookName extends string, TSelector, THookMiddleware> {
+    protected registry: HookRegistry<THookName, TSelector, THookMiddleware>;
+    constructor();
+    /**
+     * Get all possible hook names for this registry.
+     * Must be implemented by subclasses.
+     */
+    protected abstract getAllHookNames(): readonly THookName[];
+    /**
+     * Check if a value is a hook name.
+     * Can be overridden by subclasses to provide custom logic.
+     * Default implementation checks if the value is in getAllHookNames().
+     */
+    protected isHookName(value: any): value is THookName;
+    /**
+     * Register middleware for a hook.
+     *
+     * Overloads:
+     * - register(hookName, selector, middleware) - specific hook, specific selector
+     * - register(hookName, middleware) - specific hook, global selector
+     * - register(selector, middleware) - all hooks, specific selector (if selectors are supported)
+     * - register(middleware) - all hooks, global selector
+     */
+    register<T extends THookName>(hookName: T, selector: TSelector | undefined, middleware: THookMiddleware): void;
+    register<T extends THookName>(hookName: T, middleware: THookMiddleware): void;
+    register(selector: TSelector, middleware: THookMiddleware): void;
+    register(middleware: THookMiddleware): void;
+    /**
+     * Copy all hooks from another registry of the same type.
+     * Useful for inheriting hooks from parent engine to child engine.
+     *
+     * @param sourceRegistry - The registry to copy hooks from
+     */
+    copyHooksFrom(sourceRegistry: BaseHookRegistry<THookName, TSelector, THookMiddleware>): void;
+}
+//# sourceMappingURL=base-hook-registry.d.ts.map

package/dist/hooks/base-hook-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-hook-registry.d.ts","sourceRoot":"","sources":["../../src/hooks/base-hook-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;GAGG;AACH,8BAAsB,gBAAgB,CAAC,SAAS,SAAS,MAAM,EAAE,SAAS,EAAE,eAAe;IACzF,SAAS,CAAC,QAAQ,EAAE,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC;;IAMxE;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,IAAI,SAAS,SAAS,EAAE;IAE1D;;;;OAIG;IACH,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,SAAS;IAIpD;;;;;;;;OAQG;IACH,QAAQ,CAAC,CAAC,SAAS,SAAS,EAC1B,QAAQ,EAAE,CAAC,EACX,QAAQ,EAAE,SAAS,GAAG,SAAS,EAC/B,UAAU,EAAE,eAAe,GAC1B,IAAI;IACP,QAAQ,CAAC,CAAC,SAAS,SAAS,EAAE,QAAQ,EAAE,CAAC,EAAE,UAAU,EAAE,eAAe,GAAG,IAAI;IAC7E,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,GAAG,IAAI;IAChE,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAwC3C;;;;;OAKG;IACH,aAAa,CAAC,cAAc,EAAE,gBAAgB,CAAC,SAAS,EAAE,SAAS,EAAE,eAAe,CAAC,GAAG,IAAI;CAe7F"}

package/dist/hooks/base-hook-registry.js

@@ -0,0 +1,76 @@
+import { HookRegistry } from "./hook-registry";
+/**
+ * Base class for hook registries that provides common overloaded register methods.
+ * Reduces code duplication across ModelHookRegistry, ToolHookRegistry, etc.
+ */
+export class BaseHookRegistry {
+    registry;
+    constructor() {
+        this.registry = new HookRegistry();
+    }
+    /**
+     * Check if a value is a hook name.
+     * Can be overridden by subclasses to provide custom logic.
+     * Default implementation checks if the value is in getAllHookNames().
+     */
+    isHookName(value) {
+        return this.getAllHookNames().includes(value);
+    }
+    register(arg1, arg2, arg3) {
+        const allHookNames = this.getAllHookNames();
+        // Determine which overload was called
+        if (arg3 !== undefined) {
+            // register(hookName, selector, middleware)
+            const hookName = arg1;
+            const selector = arg2;
+            const middleware = arg3;
+            this.registry.register(hookName, selector, middleware);
+        }
+        else if (arg2 !== undefined) {
+            // Could be register(hookName, middleware) or register(selector, middleware)
+            // Check if arg1 is a hook name
+            if (this.isHookName(arg1)) {
+                // register(hookName, middleware) - specific hook, global selector
+                const hookName = arg1;
+                const middleware = arg2;
+                this.registry.register(hookName, undefined, middleware);
+            }
+            else {
+                // register(selector, middleware) - all hooks, specific selector
+                const selector = arg1;
+                const middleware = arg2;
+                for (const hookName of allHookNames) {
+                    this.registry.register(hookName, selector, middleware);
+                }
+            }
+        }
+        else {
+            // register(middleware) - all hooks, global selector
+            const middleware = arg1;
+            for (const hookName of allHookNames) {
+                this.registry.register(hookName, undefined, middleware);
+            }
+        }
+    }
+    /**
+     * Copy all hooks from another registry of the same type.
+     * Useful for inheriting hooks from parent engine to child engine.
+     *
+     * @param sourceRegistry - The registry to copy hooks from
+     */
+    copyHooksFrom(sourceRegistry) {
+        const allHookNames = this.getAllHookNames();
+        for (const hookName of allHookNames) {
+            const sourceHookMap = sourceRegistry.registry.getHookMap(hookName);
+            if (sourceHookMap) {
+                // Copy all middleware for each selector (including undefined for global)
+                for (const [selector, middlewareArray] of sourceHookMap.entries()) {
+                    for (const middleware of middlewareArray) {
+                        this.registry.register(hookName, selector, middleware);
+                    }
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=base-hook-registry.js.map

package/dist/hooks/base-hook-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-hook-registry.js","sourceRoot":"","sources":["../../src/hooks/base-hook-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;GAGG;AACH,MAAM,OAAgB,gBAAgB;IAC1B,QAAQ,CAAsD;IAExE;QACE,IAAI,CAAC,QAAQ,GAAG,IAAI,YAAY,EAAyC,CAAC;IAC5E,CAAC;IAQD;;;;OAIG;IACO,UAAU,CAAC,KAAU;QAC7B,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;IAmBD,QAAQ,CACN,IAAqC,EACrC,IAA8C,EAC9C,IAAsB;QAEtB,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;QAE5C,sCAAsC;QACtC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,2CAA2C;YAC3C,MAAM,QAAQ,GAAG,IAAS,CAAC;YAC3B,MAAM,QAAQ,GAAG,IAA6B,CAAC;YAC/C,MAAM,UAAU,GAAG,IAAuB,CAAC;YAC3C,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;QACzD,CAAC;aAAM,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YAC9B,4EAA4E;YAC5E,+BAA+B;YAC/B,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1B,kEAAkE;gBAClE,MAAM,QAAQ,GAAG,IAAS,CAAC;gBAC3B,MAAM,UAAU,GAAG,IAAuB,CAAC;gBAC3C,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;YAC1D,CAAC;iBAAM,CAAC;gBACN,gEAAgE;gBAChE,MAAM,QAAQ,GAAG,IAAiB,CAAC;gBACnC,MAAM,UAAU,GAAG,IAAuB,CAAC;gBAC3C,KAAK,MAAM,QAAQ,IAAI,YAAY,EAAE,CAAC;oBACpC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;gBACzD,CAAC;YACH,CAAC;QACH,CAAC;aAAM,CAAC;YACN,oDAAoD;YACpD,MAAM,UAAU,GAAG,IAAuB,CAAC;YAC3C,KAAK,MAAM,QAAQ,IAAI,YAAY,EAAE,CAAC;gBACpC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,cAAuE;QACnF,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;QAE5C,KAAK,MAAM,QAAQ,IAAI,YAAY,EAAE,CAAC;YACpC,MAAM,aAAa,GAAG,cAAc,CAAC,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YACnE,IAAI,aAAa,EAAE,CAAC;gBAClB,yEAAyE;gBACzE,KAAK,MAAM,CAAC,QAAQ,EAAE,eAAe,CAAC,IAAI,aAAa,CAAC,OAAO,EAAE,EAAE,CAAC;oBAClE,KAAK,MAAM,UAAU,IAAI,eAAe,EAAE,CAAC;wBACzC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;oBACzD,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/hooks/com-state.d.ts

@@ -0,0 +1,40 @@
+/**
+ * COM State Hook
+ *
+ * Provides state storage in the COM (Context Object Model).
+ * State persists across renders and changes trigger re-renders.
+ *
+ * This is similar to useState but:
+ * - State is stored in the shared COM, not component-local
+ * - State persists across ticks
+ * - Returns a Signal-like interface
+ *
+ * Reactivity: Subscribes to COM's "state:changed" events via a React
+ * version counter, ensuring the component re-renders when state is
+ * modified externally (e.g. from a tool handler).
+ */
+import type { Signal } from "./signal";
+/**
+ * Use state stored in the COM.
+ *
+ * @param key - Unique key for this state in the COM
+ * @param initialValue - Initial value if not already set
+ * @returns A Signal-like object for reading and writing the state
+ *
+ * @example
+ * ```tsx
+ * function StatusComponent() {
+ *   const status = useComState('status', 'pending');
+ *
+ *   // Read the value
+ *   console.log(status()); // or status.value
+ *
+ *   // Update the value
+ *   status.set('active');
+ *
+ *   return <System>Status: {status()}</System>;
+ * }
+ * ```
+ */
+export declare function useComState<T>(key: string, initialValue: T): Signal<T>;
+//# sourceMappingURL=com-state.d.ts.map

package/dist/hooks/com-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"com-state.d.ts","sourceRoot":"","sources":["../../src/hooks/com-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAgEtE"}

package/dist/hooks/com-state.js

@@ -0,0 +1,90 @@
+/**
+ * COM State Hook
+ *
+ * Provides state storage in the COM (Context Object Model).
+ * State persists across renders and changes trigger re-renders.
+ *
+ * This is similar to useState but:
+ * - State is stored in the shared COM, not component-local
+ * - State persists across ticks
+ * - Returns a Signal-like interface
+ *
+ * Reactivity: Subscribes to COM's "state:changed" events via a React
+ * version counter, ensuring the component re-renders when state is
+ * modified externally (e.g. from a tool handler).
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCom } from "./context";
+/**
+ * Use state stored in the COM.
+ *
+ * @param key - Unique key for this state in the COM
+ * @param initialValue - Initial value if not already set
+ * @returns A Signal-like object for reading and writing the state
+ *
+ * @example
+ * ```tsx
+ * function StatusComponent() {
+ *   const status = useComState('status', 'pending');
+ *
+ *   // Read the value
+ *   console.log(status()); // or status.value
+ *
+ *   // Update the value
+ *   status.set('active');
+ *
+ *   return <System>Status: {status()}</System>;
+ * }
+ * ```
+ */
+export function useComState(key, initialValue) {
+    const ctx = useCom();
+    // Initialize if needed
+    if (ctx.getState(key) === undefined) {
+        ctx.setState(key, initialValue);
+    }
+    // Version counter triggers React re-render when COM state changes externally
+    const [, setVersion] = useState(0);
+    const setVersionRef = useRef(setVersion);
+    setVersionRef.current = setVersion;
+    // Subscribe to COM "state:changed" events for this key
+    useEffect(() => {
+        const handler = (changedKey) => {
+            if (changedKey === key) {
+                setVersionRef.current((v) => v + 1);
+            }
+        };
+        ctx.on("state:changed", handler);
+        return () => {
+            ctx.off("state:changed", handler);
+        };
+    }, [ctx, key]);
+    // Read directly from COM (always fresh — works in tool handlers, effects, etc.)
+    const getValue = useCallback(() => {
+        return (ctx.getState(key) ?? initialValue);
+    }, [ctx, key, initialValue]);
+    // Set a new value — writes to COM, which emits event, which triggers re-render
+    const setValue = useCallback((value) => {
+        const currentValue = getValue();
+        const newValue = typeof value === "function" ? value(currentValue) : value;
+        ctx.setState(key, newValue);
+        ctx.requestRecompile(`COM state '${key}' changed`);
+    }, [ctx, key, getValue]);
+    // Update with function
+    const update = useCallback((fn) => {
+        setValue(fn);
+    }, [setValue]);
+    // Create the Signal-like interface — reads from COM directly, always fresh
+    const signal = useMemo(() => {
+        const fn = getValue;
+        Object.defineProperty(fn, "value", {
+            get: getValue,
+            enumerable: true,
+        });
+        fn.set = setValue;
+        fn.update = update;
+        return fn;
+    }, [getValue, setValue, update]);
+    return signal;
+}
+//# sourceMappingURL=com-state.js.map

package/dist/hooks/com-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"com-state.js","sourceRoot":"","sources":["../../src/hooks/com-state.ts"],"names":[],"mappings":"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"}

package/dist/hooks/context-info.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Context Info Hook
+ *
+ * Provides real-time access to context utilization information within JSX components.
+ * Updated by the session after each tick with token usage and model capabilities.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const contextInfo = useContextInfo();
+ *
+ *   if (contextInfo?.utilization && contextInfo.utilization > 80) {
+ *     // Context is getting full, maybe summarize or truncate
+ *     return <Section id="summary">Summarized content...</Section>;
+ *   }
+ *
+ *   return <Section id="full">Full detailed content...</Section>;
+ * }
+ * ```
+ */
+import React, { type ReactNode } from "react";
+/**
+ * Context utilization information.
+ * Updated after each tick with current token usage and model info.
+ */
+export interface ContextInfo {
+    /** Model ID (e.g., "gpt-4o", "claude-3-5-sonnet-20241022") */
+    modelId: string;
+    /** Human-readable model name */
+    modelName?: string;
+    /** Provider name (e.g., "openai", "anthropic") */
+    provider?: string;
+    /** Context window size in tokens */
+    contextWindow?: number;
+    /** Input tokens used this tick */
+    inputTokens: number;
+    /** Output tokens generated this tick */
+    outputTokens: number;
+    /** Total tokens this tick */
+    totalTokens: number;
+    /** Context utilization percentage (0-100) */
+    utilization?: number;
+    /** Max output tokens for this model */
+    maxOutputTokens?: number;
+    /** Model capabilities */
+    supportsVision?: boolean;
+    supportsToolUse?: boolean;
+    isReasoningModel?: boolean;
+    /** Estimated total context tokens (from token estimation, pre-model-call) */
+    estimatedContextTokens?: number;
+    /** Current tick number */
+    tick: number;
+    /** Cumulative usage across all ticks in this execution */
+    cumulativeUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        ticks: number;
+    };
+}
+/**
+ * Context info store - holds current context utilization state.
+ */
+export interface ContextInfoStore {
+    /** Current context info (null before first tick completes) */
+    current: ContextInfo | null;
+    /** Update the context info */
+    update: (info: ContextInfo) => void;
+    /** Clear the context info */
+    clear: () => void;
+}
+/**
+ * Create a new context info store.
+ */
+export declare function createContextInfoStore(): ContextInfoStore;
+/**
+ * Get the context info store from context.
+ * Returns null if not within a provider (for optional access).
+ */
+export declare function useContextInfoStore(): ContextInfoStore | null;
+/**
+ * Hook to access current context utilization info.
+ *
+ * Returns null if:
+ * - Not within a session (no ContextInfoProvider)
+ * - Before first tick completes
+ *
+ * @example Basic usage
+ * ```tsx
+ * function MyComponent() {
+ *   const contextInfo = useContextInfo();
+ *
+ *   if (!contextInfo) {
+ *     return null; // Not available yet
+ *   }
+ *
+ *   console.log(`Using ${contextInfo.utilization}% of context`);
+ *   return <Section id="content">...</Section>;
+ * }
+ * ```
+ *
+ * @example Conditional rendering based on context usage
+ * ```tsx
+ * function AdaptiveContent() {
+ *   const contextInfo = useContextInfo();
+ *
+ *   // If context is over 75% full, use abbreviated content
+ *   const isContextTight = contextInfo?.utilization && contextInfo.utilization > 75;
+ *
+ *   return isContextTight
+ *     ? <Section id="brief">Brief summary...</Section>
+ *     : <Section id="detailed">Full detailed content...</Section>;
+ * }
+ * ```
+ *
+ * @example Access model capabilities
+ * ```tsx
+ * function ImageTool() {
+ *   const contextInfo = useContextInfo();
+ *
+ *   // Only render image tool if model supports vision
+ *   if (!contextInfo?.supportsVision) {
+ *     return null;
+ *   }
+ *
+ *   return <Tool name="analyze_image" ... />;
+ * }
+ * ```
+ */
+export declare function useContextInfo(): ContextInfo | null;
+/**
+ * Provider for context info.
+ * Used internally by Session to make context info available to components.
+ */
+export declare function ContextInfoProvider({ store, children, }: {
+    store: ContextInfoStore;
+    children?: ReactNode;
+}): React.ReactElement;
+//# sourceMappingURL=context-info.d.ts.map

package/dist/hooks/context-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-info.d.ts","sourceRoot":"","sources":["../../src/hooks/context-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AASzE;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yBAAyB;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,6EAA6E;IAC7E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,eAAe,CAAC,EAAE;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,8BAA8B;IAC9B,MAAM,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;IACpC,6BAA6B;IAC7B,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAMD;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAczD;AAQD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,IAAI,CAE7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,cAAc,IAAI,WAAW,GAAG,IAAI,CAGnD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,gBAAgB,CAAC;IACxB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,GAAG,KAAK,CAAC,YAAY,CAErB"}

package/dist/hooks/context-info.js

@@ -0,0 +1,115 @@
+/**
+ * Context Info Hook
+ *
+ * Provides real-time access to context utilization information within JSX components.
+ * Updated by the session after each tick with token usage and model capabilities.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const contextInfo = useContextInfo();
+ *
+ *   if (contextInfo?.utilization && contextInfo.utilization > 80) {
+ *     // Context is getting full, maybe summarize or truncate
+ *     return <Section id="summary">Summarized content...</Section>;
+ *   }
+ *
+ *   return <Section id="full">Full detailed content...</Section>;
+ * }
+ * ```
+ */
+import React, { createContext, useContext } from "react";
+// Helper for createElement
+const h = React.createElement;
+// ============================================================
+// Store Factory
+// ============================================================
+/**
+ * Create a new context info store.
+ */
+export function createContextInfoStore() {
+    let current = null;
+    return {
+        get current() {
+            return current;
+        },
+        update(info) {
+            current = info;
+        },
+        clear() {
+            current = null;
+        },
+    };
+}
+// ============================================================
+// React Context
+// ============================================================
+const ContextInfoContext = createContext(null);
+/**
+ * Get the context info store from context.
+ * Returns null if not within a provider (for optional access).
+ */
+export function useContextInfoStore() {
+    return useContext(ContextInfoContext);
+}
+/**
+ * Hook to access current context utilization info.
+ *
+ * Returns null if:
+ * - Not within a session (no ContextInfoProvider)
+ * - Before first tick completes
+ *
+ * @example Basic usage
+ * ```tsx
+ * function MyComponent() {
+ *   const contextInfo = useContextInfo();
+ *
+ *   if (!contextInfo) {
+ *     return null; // Not available yet
+ *   }
+ *
+ *   console.log(`Using ${contextInfo.utilization}% of context`);
+ *   return <Section id="content">...</Section>;
+ * }
+ * ```
+ *
+ * @example Conditional rendering based on context usage
+ * ```tsx
+ * function AdaptiveContent() {
+ *   const contextInfo = useContextInfo();
+ *
+ *   // If context is over 75% full, use abbreviated content
+ *   const isContextTight = contextInfo?.utilization && contextInfo.utilization > 75;
+ *
+ *   return isContextTight
+ *     ? <Section id="brief">Brief summary...</Section>
+ *     : <Section id="detailed">Full detailed content...</Section>;
+ * }
+ * ```
+ *
+ * @example Access model capabilities
+ * ```tsx
+ * function ImageTool() {
+ *   const contextInfo = useContextInfo();
+ *
+ *   // Only render image tool if model supports vision
+ *   if (!contextInfo?.supportsVision) {
+ *     return null;
+ *   }
+ *
+ *   return <Tool name="analyze_image" ... />;
+ * }
+ * ```
+ */
+export function useContextInfo() {
+    const store = useContext(ContextInfoContext);
+    return store?.current ?? null;
+}
+/**
+ * Provider for context info.
+ * Used internally by Session to make context info available to components.
+ */
+export function ContextInfoProvider({ store, children, }) {
+    return h(ContextInfoContext.Provider, { value: store }, children);
+}
+//# sourceMappingURL=context-info.js.map

package/dist/hooks/context-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-info.js","sourceRoot":"","sources":["../../src/hooks/context-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,EAAE,aAAa,EAAE,UAAU,EAAkB,MAAM,OAAO,CAAC;AAEzE,2BAA2B;AAC3B,MAAM,CAAC,GAAG,KAAK,CAAC,aAAa,CAAC;AA0D9B,+DAA+D;AAC/D,gBAAgB;AAChB,+DAA+D;AAE/D;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,IAAI,OAAO,GAAuB,IAAI,CAAC;IAEvC,OAAO;QACL,IAAI,OAAO;YACT,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,MAAM,CAAC,IAAiB;YACtB,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;QACD,KAAK;YACH,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,+DAA+D;AAC/D,gBAAgB;AAChB,+DAA+D;AAE/D,MAAM,kBAAkB,GAAG,aAAa,CAA0B,IAAI,CAAC,CAAC;AAExE;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,UAAU,CAAC,kBAAkB,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,KAAK,GAAG,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAC7C,OAAO,KAAK,EAAE,OAAO,IAAI,IAAI,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAClC,KAAK,EACL,QAAQ,GAIT;IACC,OAAO,CAAC,CAAC,kBAAkB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,CAAC;AACpE,CAAC"}