@agentick/core 0.0.1

package/dist/component/component.d.ts

@@ -0,0 +1,314 @@
+import type { COMInput, COMOutput } from "../com/types";
+import type { COM } from "../com/object-model";
+import type { JSX } from "../jsx/jsx-runtime";
+import type { StopReason, UsageStats } from "@agentick/shared";
+import type { ExecutableTool } from "../tool/tool";
+import { type ComponentHookMiddleware, ComponentHookRegistry } from "./component-hooks";
+import type { ChannelService } from "../channels";
+import { type CompiledStructure } from "../compiler/types";
+import type { ExecutionMessage } from "../engine/execution-types";
+/**
+ * Stop reason information for components to react to.
+ */
+export interface StopReasonInfo {
+    /**
+     * The stop reason code (from StopReason enum or custom string).
+     */
+    reason: string | StopReason;
+    /**
+     * Human-readable description of why execution stopped.
+     */
+    description?: string;
+    /**
+     * Whether this stop reason allows for recovery/retry.
+     */
+    recoverable?: boolean;
+    /**
+     * Additional metadata about the stop reason.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Error information for components to react to.
+ */
+export interface EngineError {
+    /**
+     * The error that occurred.
+     */
+    error: Error;
+    /**
+     * Phase where the error occurred.
+     */
+    phase: "render" | "model_execution" | "tool_execution" | "tick_start" | "tick_end" | "complete" | "unknown";
+    /**
+     * Additional context about the error.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Whether this error is recoverable.
+     */
+    recoverable?: boolean;
+}
+/**
+ * Recovery action that components can return from onError.
+ */
+export interface RecoveryAction {
+    /**
+     * Whether to continue execution after recovery.
+     */
+    continue: boolean;
+    /**
+     * Optional message to add to the timeline explaining the recovery.
+     */
+    recoveryMessage?: string;
+    /**
+     * Optional modifications to make to the COM before continuing.
+     */
+    modifications?: (ctx: COM) => void | Promise<void>;
+}
+export interface TickState {
+    /**
+     * Current tick number (1-indexed).
+     */
+    tick: number;
+    /**
+     * The COMInput from the previous tick (what was sent to model.fromEngineState).
+     * This is the compiled state that was passed to the model.
+     */
+    previous?: COMInput;
+    /**
+     * The COMOutput from the last tick (what was produced by model execution and tool execution).
+     * Contains new timeline entries, tool calls, and tool results.
+     *
+     * On tick 1, before model execution, this contains userInput (timeline, sections)
+     * to allow components to render purely from previous + current.
+     */
+    current?: COMOutput;
+    /**
+     * Stop reason information from the last model execution.
+     * Components can use this to handle graceful recovery, retries, etc.
+     */
+    stopReason?: StopReasonInfo;
+    /**
+     * Token usage from the last model execution.
+     * Contains inputTokens, outputTokens, totalTokens, and optional reasoning/cache tokens.
+     */
+    usage?: UsageStats;
+    /**
+     * Error information if an error occurred during execution.
+     * Components can use this to handle errors and potentially recover.
+     */
+    error?: EngineError;
+    /**
+     * Signal the engine to stop execution after this tick.
+     * @param reason The reason for stopping.
+     */
+    stop: (reason: string) => void;
+    /**
+     * Messages queued since the last tick.
+     *
+     * Messages are delivered immediately to onMessage hooks when they arrive,
+     * then queued here for availability during render. This allows components
+     * to access all messages received since the last tick in their render logic.
+     *
+     * The queue is cleared after each tick completes.
+     */
+    queuedMessages: ExecutionMessage[];
+    /**
+     * Channel service for bidirectional communication (optional).
+     * Components can publish/subscribe to channels for UI integration.
+     */
+    channels?: ChannelService;
+}
+/**
+ * Context provided to onAfterCompile hook.
+ * Contains metadata about the current compilation iteration.
+ */
+export interface AfterCompileContext {
+    /**
+     * Current compilation iteration (0-indexed).
+     */
+    iteration: number;
+    /**
+     * Maximum allowed iterations before forced stabilization.
+     */
+    maxIterations: number;
+}
+export interface EngineComponent {
+    name?: string;
+    /**
+     * The channels declaration for the component.
+     * Components can declare channels to publish and subscribe to.
+     */
+    tool?: ExecutableTool;
+    /**
+     * Called when the component is mounted to the engine.
+     * Use this to register static resources like tools.
+     * @param ctx The persistent Context Object Model for this execution.
+     */
+    onMount?: (ctx: COM) => Promise<void> | void;
+    /**
+     * Called when the component is unmounted from the engine.
+     * @param ctx The persistent Context Object Model for this execution.
+     */
+    onUnmount?: (ctx: COM) => Promise<void> | void;
+    /**
+     * Called once before the first tick, after the COM is created.
+     * Use this for initialization that needs to happen before execution starts.
+     * @param ctx The persistent Context Object Model for this execution.
+     */
+    onStart?: (ctx: COM) => Promise<void> | void;
+    onTickStart?: (ctx: COM, state: TickState) => Promise<void> | void;
+    /**
+     * Declaratively render context for the current tick.
+     * Components should interact with the COM to compose the context.
+     * OR return a Virtual DOM tree (JSX.Element) to be rendered by the Engine.
+     * @param ctx The persistent Context Object Model for this execution.
+     * @param state Current tick state including input and previous render.
+     */
+    render?: (ctx: COM, state: TickState) => Promise<void | JSX.Element | null> | void | JSX.Element | null;
+    /**
+     * Called after each compilation pass, before the final render is applied.
+     * Use this to inspect the compiled structure and potentially request re-compilation
+     * if state changes are needed (e.g., context summarization, tool adjustments).
+     *
+     * The compilation loop continues until no component calls `ctx.requestRecompile()`
+     * or the maximum iteration limit is reached.
+     *
+     * @param ctx The persistent Context Object Model for this execution.
+     * @param compiled The compiled structure from this compilation pass.
+     * @param state Current tick state.
+     * @param afterCompileCtx Context containing iteration metadata.
+     */
+    onAfterCompile?: (ctx: COM, compiled: CompiledStructure, state: TickState, afterCompileCtx: AfterCompileContext) => Promise<void> | void;
+    /**
+     * Called after model execution completes for this tick.
+     * At this point, current is available (contains model outputs from this tick).
+     * Use this for per-tick processing, validation, or side effects.
+     * Note: Model outputs are automatically included in the next tick's previous.
+     * @param ctx The persistent Context Object Model for this execution.
+     * @param state Current tick state including previous and current.
+     */
+    onTickEnd?: (ctx: COM, state: TickState) => Promise<void> | void;
+    /**
+     * Called after the entire execution completes (all ticks finished).
+     * At this point, the final COMInput is available.
+     * Use this for final state processing, persistence, reporting, side effects, etc.
+     * Called before onUnmount.
+     *
+     * Note: This is for side effects only, not rendering. Rendering should happen in render().
+     * Model outputs are automatically included in the final COM state.
+     * @param ctx The persistent Context Object Model for this execution.
+     * @param finalState The final COMInput state after all ticks.
+     */
+    onComplete?: (ctx: COM, finalState: COMInput) => Promise<void> | void;
+    /**
+     * Called immediately when a message is sent to the running execution.
+     *
+     * Messages can arrive via:
+     * - RuntimeSession.sendMessage() - Direct programmatic injection
+     * - ExecutionHandle.send() - Via handle reference
+     * - Channel events with type='message' - From client
+     *
+     * This hook is called immediately when the message arrives, not at tick boundaries.
+     * Use ctx.abort() to interrupt execution if needed, or update state for the next tick.
+     * Messages are also available in TickState.queuedMessages during render.
+     *
+     * @param ctx The persistent Context Object Model for this execution.
+     * @param message The message sent to the execution.
+     * @param state Current tick state.
+     *
+     * @example
+     * ```typescript
+     * class InteractiveAgent extends Component {
+     *   onMessage(ctx, message, state) {
+     *     if (message.type === 'stop') {
+     *       ctx.abort('User requested stop');
+     *     } else if (message.type === 'feedback') {
+     *       ctx.setState('userFeedback', message.content);
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    onMessage?: (ctx: COM, message: ExecutionMessage, state: TickState) => Promise<void> | void;
+    /**
+     * Called when an error occurs during engine execution.
+     * Components can use this to handle errors and potentially recover.
+     *
+     * @param ctx The persistent Context Object Model for this execution.
+     * @param state Current tick state including error information.
+     * @returns RecoveryAction to indicate whether to continue execution, or void/undefined to let error propagate
+     */
+    onError?: (ctx: COM, state: TickState) => Promise<RecoveryAction | void> | RecoveryAction | void;
+}
+export type ComponentClass = new (props?: any) => EngineComponent;
+export type ComponentFactory = (props?: any) => EngineComponent | Promise<EngineComponent>;
+export type PureFunctionComponent<P = any> = ((props: P) => JSX.Element | null) | ((props: P, ctx: COM, state: TickState) => JSX.Element | null);
+export type ComponentDefinition = EngineComponent | ComponentClass | ComponentFactory | PureFunctionComponent | JSX.Element;
+/**
+ * Base class for Stateful Components
+ */
+export declare abstract class Component<P = {}, S = {}> implements EngineComponent {
+    static hooks: Record<string, ComponentHookMiddleware<any>[]>;
+    static tags: string[];
+    private hooksRegistry;
+    get hooks(): ComponentHookRegistry;
+    props: P;
+    state: S;
+    constructor(props?: P);
+    private registerStaticHooks;
+    onMount(_ctx: COM): void;
+    onUnmount(_ctx: COM): void;
+    onStart(_ctx: COM): void;
+    onTickStart(_ctx: COM, _state: TickState): void;
+    onAfterCompile(_ctx: COM, _compiled: CompiledStructure, _state: TickState, _afterCompileCtx: AfterCompileContext): void;
+    onTickEnd(_ctx: COM, _state: TickState): void;
+    onComplete(_ctx: COM, _finalState: COMInput): void;
+    onError(_ctx: COM, _state: TickState): RecoveryAction | void;
+    onMessage(_ctx: COM, _message: ExecutionMessage, _state: TickState): void | Promise<void>;
+    render(_ctx: COM, _state: TickState): Promise<void | JSX.Element | null> | void | JSX.Element | null;
+}
+export interface OnMount {
+    onMount: (ctx: COM) => Promise<void> | void;
+}
+export interface OnUnmount {
+    onUnmount: (ctx: COM) => Promise<void> | void;
+}
+export interface OnStart {
+    onStart: (ctx: COM) => Promise<void> | void;
+}
+export interface OnTickStart {
+    onTickStart: (ctx: COM, state: TickState) => Promise<void> | void;
+}
+export interface OnAfterCompile {
+    onAfterCompile: (ctx: COM, compiled: CompiledStructure, state: TickState, afterCompileCtx: AfterCompileContext) => Promise<void> | void;
+}
+export interface OnTickEnd {
+    onTickEnd: (ctx: COM, state: TickState) => Promise<void> | void;
+}
+export interface OnComplete {
+    onComplete: (ctx: COM, finalState: COMInput) => Promise<void> | void;
+}
+export interface OnError {
+    onError: (ctx: COM, state: TickState) => Promise<RecoveryAction | void> | RecoveryAction | void;
+}
+export interface OnMessage {
+    onMessage: (ctx: COM, message: ExecutionMessage, state: TickState) => Promise<void> | void;
+}
+export interface Render {
+    render: (ctx: COM, state: TickState) => Promise<void | JSX.Element | null> | void | JSX.Element | null;
+}
+export interface ComponentLifecycleHooks {
+    onMount?: OnMount;
+    onUnmount?: OnUnmount;
+    onStart?: OnStart;
+    onTickStart?: OnTickStart;
+    onAfterCompile?: OnAfterCompile;
+    onTickEnd?: OnTickEnd;
+    onMessage?: OnMessage;
+    onComplete?: OnComplete;
+    onError?: OnError;
+    render?: Render;
+}
+//# sourceMappingURL=component.d.ts.map

package/dist/component/component.d.ts.map

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

package/dist/component/component.js

@@ -0,0 +1,64 @@
+import { ComponentHookRegistry, } from "./component-hooks";
+import {} from "../compiler/types";
+/**
+ * Base class for Stateful Components
+ */
+export class Component {
+    static hooks = {};
+    static tags = [];
+    hooksRegistry;
+    get hooks() {
+        return this.hooksRegistry;
+    }
+    props;
+    state;
+    constructor(props = {}) {
+        this.hooksRegistry = new ComponentHookRegistry();
+        this.registerStaticHooks();
+        this.props = props;
+        this.state = {};
+    }
+    registerStaticHooks() {
+        const componentClass = this.constructor;
+        const staticHooks = componentClass.hooks;
+        if (!staticHooks) {
+            return;
+        }
+        for (const [hookName, middleware] of Object.entries(staticHooks)) {
+            if (middleware && Array.isArray(middleware)) {
+                for (const mw of middleware) {
+                    this.hooksRegistry.register(hookName, mw);
+                }
+            }
+        }
+    }
+    // Default implementations - all optional
+    // Note: Signal binding and ref handling are now done automatically by the compiler.
+    // Components can override onMount/onUnmount for custom logic, but don't need to
+    // call super.onMount()/super.onUnmount() for basic signal/ref handling.
+    onMount(_ctx) {
+        // Override for custom mount logic
+        // Signal binding and ref handling are handled automatically by the compiler
+    }
+    onUnmount(_ctx) {
+        // Override for custom unmount logic
+        // Signal cleanup and ref removal are handled automatically by the compiler
+    }
+    onStart(_ctx) { }
+    onTickStart(_ctx, _state) { }
+    onAfterCompile(_ctx, _compiled, _state, _afterCompileCtx) { }
+    onTickEnd(_ctx, _state) { }
+    onComplete(_ctx, _finalState) { }
+    onError(_ctx, _state) {
+        // Default: let error propagate (no recovery)
+        return undefined;
+    }
+    onMessage(_ctx, _message, _state) {
+        // Override to handle messages sent to the execution
+    }
+    // Render is optional - components can just manage state or provide side effects
+    render(_ctx, _state) {
+        return null;
+    }
+}
+//# sourceMappingURL=component.js.map

package/dist/component/component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../src/component/component.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAA0B,MAAM,mBAAmB,CAAC;AA+S3D;;GAEG;AACH,MAAM,OAAgB,SAAS;IAC7B,MAAM,CAAC,KAAK,GAAmD,EAAE,CAAC;IAClE,MAAM,CAAC,IAAI,GAAa,EAAE,CAAC;IAEnB,aAAa,CAAwB;IAE7C,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED,KAAK,CAAI;IACT,KAAK,CAAI;IAET,YAAY,QAAW,EAAO;QAC5B,IAAI,CAAC,aAAa,GAAG,IAAI,qBAAqB,EAAE,CAAC;QACjD,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,EAAO,CAAC;IACvB,CAAC;IAEO,mBAAmB;QACzB,MAAM,cAAc,GAAG,IAAI,CAAC,WAA+B,CAAC;QAC5D,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC;QAEzC,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QAED,KAAK,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;YACjE,IAAI,UAAU,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC5C,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;oBAC5B,IAAI,CAAC,aAAa,CAAC,QAAQ,CACzB,QAA6B,EAC7B,EAAgD,CACjD,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,yCAAyC;IACzC,oFAAoF;IACpF,gFAAgF;IAChF,wEAAwE;IACxE,OAAO,CAAC,IAAS;QACf,kCAAkC;QAClC,4EAA4E;IAC9E,CAAC;IAED,SAAS,CAAC,IAAS;QACjB,oCAAoC;QACpC,2EAA2E;IAC7E,CAAC;IACD,OAAO,CAAC,IAAS,IAAG,CAAC;IACrB,WAAW,CAAC,IAAS,EAAE,MAAiB,IAAG,CAAC;IAC5C,cAAc,CACZ,IAAS,EACT,SAA4B,EAC5B,MAAiB,EACjB,gBAAqC,IACpC,CAAC;IACJ,SAAS,CAAC,IAAS,EAAE,MAAiB,IAAG,CAAC;IAC1C,UAAU,CAAC,IAAS,EAAE,WAAqB,IAAS,CAAC;IACrD,OAAO,CAAC,IAAS,EAAE,MAAiB;QAClC,6CAA6C;QAC7C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,SAAS,CAAC,IAAS,EAAE,QAA0B,EAAE,MAAiB;QAChE,oDAAoD;IACtD,CAAC;IAED,gFAAgF;IAChF,MAAM,CACJ,IAAS,EACT,MAAiB;QAEjB,OAAO,IAAI,CAAC;IACd,CAAC"}

package/dist/component/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * # Agentick Components
+ *
+ * Base component system for Agentick agents. Provides class-based components
+ * with lifecycle hooks, signals, and render methods.
+ *
+ * ## Features
+ *
+ * - **Lifecycle Hooks** - onMount, onUnmount, onTickStart, onTickEnd
+ * - **Signals** - Reactive state within components
+ * - **Render Method** - JSX output for each tick
+ *
+ * ## Quick Start
+ *
+ * ```tsx
+ * import { Component } from 'agentick';
+ *
+ * class MyAgent extends Component {
+ *   count = signal(0);
+ *
+ *   onMount() {
+ *     console.log('Agent mounted');
+ *   }
+ *
+ *   onTickStart(ctx, state) {
+ *     this.count.value++;
+ *   }
+ *
+ *   render() {
+ *     return (
+ *       <>
+ *         <System>You are helpful.</System>
+ *         <User>Count: {this.count.value}</User>
+ *       </>
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Component} - Base component class
+ * @see {@link ComponentLifecycleHooks} - Lifecycle hook interfaces
+ *
+ * @module agentick/component
+ */
+export * from "./component";
+export * from "./component-hooks";
+//# sourceMappingURL=index.d.ts.map

package/dist/component/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/component/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC"}

package/dist/component/index.js

@@ -0,0 +1,47 @@
+/**
+ * # Agentick Components
+ *
+ * Base component system for Agentick agents. Provides class-based components
+ * with lifecycle hooks, signals, and render methods.
+ *
+ * ## Features
+ *
+ * - **Lifecycle Hooks** - onMount, onUnmount, onTickStart, onTickEnd
+ * - **Signals** - Reactive state within components
+ * - **Render Method** - JSX output for each tick
+ *
+ * ## Quick Start
+ *
+ * ```tsx
+ * import { Component } from 'agentick';
+ *
+ * class MyAgent extends Component {
+ *   count = signal(0);
+ *
+ *   onMount() {
+ *     console.log('Agent mounted');
+ *   }
+ *
+ *   onTickStart(ctx, state) {
+ *     this.count.value++;
+ *   }
+ *
+ *   render() {
+ *     return (
+ *       <>
+ *         <System>You are helpful.</System>
+ *         <User>Count: {this.count.value}</User>
+ *       </>
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Component} - Base component class
+ * @see {@link ComponentLifecycleHooks} - Lifecycle hook interfaces
+ *
+ * @module agentick/component
+ */
+export * from "./component";
+export * from "./component-hooks";
+//# sourceMappingURL=index.js.map

package/dist/component/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/component/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC"}

package/dist/component/tentickle-component.d.ts

@@ -0,0 +1,185 @@
+/**
+ * TentickleComponent - React.Component base class for Tentickle
+ *
+ * Extends React.Component to work seamlessly with the reconciler while providing
+ * access to Tentickle-specific features like COM, TickState, and lifecycle hooks.
+ *
+ * @example
+ * ```tsx
+ * class MyAgent extends TentickleComponent {
+ *   onTickStart() {
+ *     console.log(`Tick ${this.tickState.tick} starting`);
+ *   }
+ *
+ *   render() {
+ *     const history = this.tickState.previous?.timeline ?? [];
+ *     return (
+ *       <>
+ *         <Section id="system" audience="model">
+ *           You are a helpful assistant.
+ *         </Section>
+ *         {history.map((entry, i) => (
+ *           <Message key={i} {...entry.message} />
+ *         ))}
+ *       </>
+ *     );
+ *   }
+ * }
+ * ```
+ */
+import React, { type ReactNode } from "react";
+import type { COM } from "../com/object-model";
+import type { TickState, TickResult } from "../hooks/types";
+import type { COMInput } from "../com/types";
+import type { CompiledStructure } from "../compiler/types";
+import type { ExecutionMessage } from "../engine/execution-types";
+import type { RecoveryAction, AfterCompileContext } from "./component";
+/**
+ * Internal context values provided to TentickleComponent.
+ */
+interface TentickleContextValues {
+    com: COM | null;
+    tickState: TickState | null;
+}
+/**
+ * Props type that TentickleComponent accepts.
+ */
+export interface TentickleComponentProps {
+    children?: ReactNode;
+}
+/**
+ * Base class for class-based Tentickle components.
+ *
+ * Extends React.Component and provides:
+ * - Access to COM via `this.com`
+ * - Access to TickState via `this.tickState`
+ * - Tentickle lifecycle methods (onMount, onTickStart, etc.)
+ *
+ * @example
+ * ```tsx
+ * class TaskAgent extends TentickleComponent<{ maxTasks?: number }> {
+ *   onMount() {
+ *     console.log('Agent mounted');
+ *   }
+ *
+ *   onTickStart() {
+ *     console.log(`Starting tick ${this.tickState.tick}`);
+ *   }
+ *
+ *   render() {
+ *     return (
+ *       <Section id="system" audience="model">
+ *         You can manage up to {this.props.maxTasks ?? 10} tasks.
+ *       </Section>
+ *     );
+ *   }
+ * }
+ *
+ * // Usage
+ * <TaskAgent maxTasks={5} />
+ * ```
+ */
+export declare abstract class TentickleComponent<P extends object = {}, S = {}> extends React.Component<P & TentickleComponentProps, S> {
+    private _com;
+    private _tickState;
+    private _mounted;
+    private _lastTick;
+    /**
+     * Access the Context Object Model.
+     * Provides access to timeline, sections, tools, state, and more.
+     */
+    protected get com(): COM;
+    /**
+     * Access the current tick state.
+     * Provides tick number, previous output, current output, and stop control.
+     */
+    protected get tickState(): TickState;
+    /**
+     * Shortcut to get the previous timeline (conversation history).
+     */
+    protected get history(): import("../com").COMTimelineEntry[];
+    /**
+     * Shortcut to get the current tick number.
+     */
+    protected get tick(): number;
+    /**
+     * Internal: Set context values from wrapper.
+     */
+    _setContextValues(values: TentickleContextValues): void;
+    /**
+     * Internal: Render with lifecycle management.
+     *
+     * Note: onTickEnd is not called from class components directly.
+     * Use useTickEnd hook or createTool for tick end callbacks.
+     */
+    _renderWithLifecycle(): React.ReactElement | null;
+    /**
+     * Called when the component is first mounted.
+     * Use for initialization, registering tools, etc.
+     */
+    onMount?(): void | Promise<void>;
+    /**
+     * Called when the component is unmounted.
+     * Use for cleanup.
+     */
+    onUnmount?(): void | Promise<void>;
+    /**
+     * Called at the start of each tick.
+     * Use for per-tick initialization or state updates.
+     * Receives COM and TickState for consistency with hooks API.
+     */
+    onTickStart?(com: COM, tickState: TickState): void | Promise<void>;
+    /**
+     * Called at the end of each tick.
+     * Use for per-tick cleanup, side effects, or continuation control.
+     * Receives COM and TickResult with response data and control methods.
+     */
+    onTickEnd?(com: COM, result: TickResult): void | Promise<void>;
+    /**
+     * Called after compilation, before model execution.
+     * Use to inspect or modify the compiled structure.
+     */
+    onAfterCompile?(compiled: CompiledStructure, ctx: AfterCompileContext): void | Promise<void>;
+    /**
+     * Called when execution completes.
+     * Use for final cleanup or persistence.
+     */
+    onComplete?(finalState: COMInput): void | Promise<void>;
+    /**
+     * Called when a message is received during execution.
+     */
+    onMessage?(message: ExecutionMessage): void | Promise<void>;
+    /**
+     * Called when an error occurs.
+     * Return a RecoveryAction to handle the error.
+     */
+    onError?(): RecoveryAction | void;
+    /**
+     * Render the component's JSX output.
+     * Override this to define your component's UI.
+     */
+    abstract render(): ReactNode;
+    componentWillUnmount(): void;
+}
+/**
+ * Create a functional component from a TentickleComponent class.
+ *
+ * This is needed because React's reconciler needs a function component
+ * to consume contexts and create the class instance.
+ *
+ * @example
+ * ```tsx
+ * class MyAgent extends TentickleComponent {
+ *   render() { return <Section id="system">Hello</Section>; }
+ * }
+ *
+ * // Create the usable component
+ * const MyAgentComponent = createClassComponent(MyAgent);
+ *
+ * // Use in JSX
+ * <MyAgentComponent />
+ * ```
+ */
+export declare function createClassComponent<P extends object>(ComponentClass: new (props: P) => TentickleComponent<P>): React.FC<P>;
+export type { TentickleContextValues, AfterCompileContext, RecoveryAction };
+//# sourceMappingURL=tentickle-component.d.ts.map