@agentick/core 0.2.0 → 0.3.0

package/README.md

@@ -40,7 +40,9 @@ function MyApp() {
 // Create and run
 const app = createApp(MyApp, { model: createOpenAIModel() });
 const session = await app.session();
-await session.send({ messages: [{ role: "user", content: [{ type: "text", text: "What is 2 + 2?" }] }] }).result;
+await session.send({
+  messages: [{ role: "user", content: [{ type: "text", text: "What is 2 + 2?" }] }],
+}).result;
 ```
 
 ## Level 0: `createAgent` (No JSX Required)
@@ -151,11 +153,11 @@ When `maxTokens` is set, Timeline automatically compacts entries that exceed the
 
 ```typescript
 interface TokenBudgetInfo {
-  maxTokens: number;       // configured budget
+  maxTokens: number; // configured budget
   effectiveBudget: number; // maxTokens - headroom
-  currentTokens: number;   // tokens in kept entries
-  evictedCount: number;    // entries dropped
-  isCompacted: boolean;    // whether compaction fired
+  currentTokens: number; // tokens in kept entries
+  evictedCount: number; // entries dropped
+  isCompacted: boolean; // whether compaction fired
 }
 ```
 
@@ -180,8 +182,7 @@ Group content with semantic meaning:
 
 ```tsx
 <Section id="context" title="Current Context">
-  Today is {new Date().toDateString()}.
-  User is logged in as {user.name}.
+  Today is {new Date().toDateString()}. User is logged in as {user.name}.
 </Section>
 ```
 
@@ -254,15 +255,15 @@ function MyComponent() {
   const counter = useSignal(0);
   const doubled = useComputed(() => counter() * 2, [counter]);
 
-  counter();              // read: 0
-  counter.set(5);         // write
-  counter.update(v => v + 1); // update with function
-  doubled();              // read: 12
+  counter(); // read: 0
+  counter.set(5); // write
+  counter.update((v) => v + 1); // update with function
+  doubled(); // read: 12
 
   // COM state (persisted across ticks, shared between components)
   // Returns Signal<T>, NOT a tuple
   const notes = useComState<string[]>("notes", []);
-  notes();                // read current value
+  notes(); // read current value
   notes.set(["a", "b"]); // write new value
 }
 ```
@@ -272,7 +273,14 @@ function MyComponent() {
 All lifecycle hooks follow the pattern: data first, COM (context) last.
 
 ```tsx
-import { useOnMount, useOnUnmount, useOnTickStart, useOnTickEnd, useAfterCompile, useContinuation } from "@agentick/core";
+import {
+  useOnMount,
+  useOnUnmount,
+  useOnTickStart,
+  useOnTickEnd,
+  useAfterCompile,
+  useContinuation,
+} from "@agentick/core";
 
 function MyComponent() {
   // Called when component mounts
@@ -304,7 +312,7 @@ function MyComponent() {
   useContinuation((result) => {
     // Return true to continue, false to stop
     if (result.text?.includes("<DONE>")) return false;
-    if (result.tick >= 10) return false;  // Safety limit
+    if (result.tick >= 10) return false; // Safety limit
     return true;
   });
 
@@ -376,7 +384,9 @@ function Agent() {
   const [temp] = useKnob("temp", 0.7, {
     description: "Temperature",
     group: "Model",
-    min: 0, max: 2, step: 0.1,
+    min: 0,
+    max: 2,
+    step: 0.1,
   });
 
   // Boolean → model sees [toggle] type
@@ -496,13 +506,13 @@ function ContextAwareComponent() {
 ```typescript
 interface ContextInfo {
   // Model identification
-  modelId: string;           // "gpt-4o", "claude-3-5-sonnet", etc.
-  modelName?: string;        // Human-readable name
-  provider?: string;         // "openai", "anthropic", etc.
+  modelId: string; // "gpt-4o", "claude-3-5-sonnet", etc.
+  modelName?: string; // Human-readable name
+  provider?: string; // "openai", "anthropic", etc.
 
   // Context limits
-  contextWindow?: number;    // Total context window size
-  maxOutputTokens?: number;  // Max output tokens for model
+  contextWindow?: number; // Total context window size
+  maxOutputTokens?: number; // Max output tokens for model
 
   // Token usage (current tick)
   inputTokens: number;
@@ -510,7 +520,7 @@ interface ContextInfo {
   totalTokens: number;
 
   // Utilization
-  utilization?: number;      // Percentage (0-100)
+  utilization?: number; // Percentage (0-100)
 
   // Model capabilities
   supportsVision?: boolean;
@@ -518,7 +528,7 @@ interface ContextInfo {
   isReasoningModel?: boolean;
 
   // Execution info
-  tick: number;              // Current tick number
+  tick: number; // Current tick number
 
   // Cumulative usage across all ticks
   cumulativeUsage?: {
@@ -543,7 +553,7 @@ const contextInfoStore = createContextInfoStore();
 // Provide to components
 <ContextInfoProvider store={contextInfoStore}>
   <MyApp />
-</ContextInfoProvider>
+</ContextInfoProvider>;
 
 // Update the store
 contextInfoStore.update({
@@ -579,11 +589,7 @@ const WeatherTool = createTool({
     return [{ type: "text", text: JSON.stringify(weather) }];
   },
   // Optional: render state to model context (receives tickState, ctx)
-  render: (tickState, ctx) => (
-    <Section id="weather-info">
-      Last checked: {lastChecked}
-    </Section>
-  ),
+  render: (tickState, ctx) => <Section id="weather-info">Last checked: {lastChecked}</Section>,
 });
 
 // Use in your app
@@ -607,7 +613,7 @@ import { createApp } from "@agentick/core";
 
 const app = createApp(MyApp, {
   model: myModel,
-  devTools: true,  // Enable DevTools
+  devTools: true, // Enable DevTools
 });
 ```
 
@@ -620,6 +626,7 @@ const app = createApp(MyApp, {
   devTools: true,              // Enable DevTools emission
   tools: [ExternalTool],       // Additional tools (merged with JSX <Tool>s)
   mcpServers: { ... },         // MCP server configs
+  environment: myEnv,          // Execution environment (see below)
 });
 ```
 
@@ -638,11 +645,17 @@ const app = createApp(MyApp, {
   onError: (error) => console.error(error),
 
   // All events (fine-grained)
-  onEvent: (event) => { /* handle any stream event */ },
+  onEvent: (event) => {
+    /* handle any stream event */
+  },
 
   // Send lifecycle
-  onBeforeSend: (session, input) => { /* modify input */ },
-  onAfterSend: (session, result) => { /* post-processing */ },
+  onBeforeSend: (session, input) => {
+    /* modify input */
+  },
+  onAfterSend: (session, result) => {
+    /* post-processing */
+  },
 
   // Tool confirmation
   onToolConfirmation: async (call, message) => {
@@ -689,18 +702,17 @@ const handle = await session.spawn(
 );
 
 // Spawn with a JSX element (props from element + input.props are merged)
-const handle = await session.spawn(
-  <Researcher query="quantum computing" />,
-  { messages: [{ role: "user", content: [{ type: "text", text: "Go" }] }] },
-);
+const handle = await session.spawn(<Researcher query="quantum computing" />, {
+  messages: [{ role: "user", content: [{ type: "text", text: "Go" }] }],
+});
 ```
 
 **Parallel spawns** work with `Promise.all`:
 
 ```tsx
 const [researchResult, factCheckResult] = await Promise.all([
-  session.spawn(Researcher, { messages }).then(h => h.result),
-  session.spawn(FactChecker, { messages }).then(h => h.result),
+  session.spawn(Researcher, { messages }).then((h) => h.result),
+  session.spawn(FactChecker, { messages }).then((h) => h.result),
 ]);
 ```
 
@@ -730,34 +742,138 @@ const DelegateTool = createTool({
 - **Depth limit**: Maximum 10 levels of nesting (throws if exceeded).
 - **Cleanup**: Children are removed from `session.children` when they complete.
 
-### Session Persistence & Hibernation
+### Session Persistence
 
-Control hibernation, limits, and auto-cleanup:
+Sessions auto-persist after each execution and auto-restore when accessed via `app.session(id)`.
 
 ```typescript
 const app = createApp(MyApp, {
   model,
   sessions: {
-    store: new RedisSessionStore(redis),  // Or ":memory:" for SQLite
-    maxActive: 100,                        // Max concurrent sessions
-    idleTimeout: 5 * 60 * 1000,           // Hibernate after 5 min idle
-    autoHibernate: true,                  // Auto-hibernate on idle
+    store: "./data/sessions.db", // SQLite file (or ':memory:', or custom SessionStore)
+    maxActive: 100, // Max concurrent in-memory sessions
+    idleTimeout: 5 * 60 * 1000, // Evict from memory after 5 min idle
   },
+});
+```
+
+**How it works:**
+
+1. After each execution, session state is auto-saved to the store (fire-and-forget — persist failures don't block execution)
+2. When `app.session("user-123")` is called and the session isn't in memory, it's auto-restored from the store
+3. `useComState` and `useData` values are included in snapshots by default (set `{ persist: false }` to exclude)
+4. `maxActive` and `idleTimeout` control memory — evicted sessions can be restored from store
 
-  // Session lifecycle hooks
-  onSessionCreate: (session) => { /* ... */ },
-  onSessionClose: (sessionId) => { /* ... */ },
+#### Snapshot Contents
 
-  // Hibernation hooks
-  onBeforeHibernate: (session, snapshot) => {
-    // Return false to cancel, modified snapshot, or void
-    if (session.inspect().lastToolCalls.length > 0) return false;
+A `SessionSnapshot` captures:
+
+| Field       | Type                        | Description                                            |
+| ----------- | --------------------------- | ------------------------------------------------------ |
+| `timeline`  | `COMTimelineEntry[] ∣ null` | Full conversation history                              |
+| `comState`  | `Record<string, unknown>`   | All `useComState` values (with `persist !== false`)    |
+| `dataCache` | `Record<string, ...>`       | All `useData` cached values (with `persist !== false`) |
+| `tick`      | `number`                    | Tick count at snapshot time                            |
+| `usage`     | `UsageStats`                | Accumulated token usage                                |
+
+#### Lifecycle Hooks
+
+```typescript
+const app = createApp(MyApp, {
+  model,
+  sessions: { store: "./sessions.db" },
+
+  // Before save — cancel or modify snapshot
+  onBeforePersist: (session, snapshot) => {
+    if (snapshot.tick < 2) return false; // Don't persist short sessions
+  },
+
+  // After save
+  onAfterPersist: (sessionId, snapshot) => {
+    console.log(`Saved session ${sessionId}`);
   },
-  onAfterHibernate: (sessionId, snapshot) => { /* ... */ },
-  onBeforeHydrate: (sessionId, snapshot) => {
-    // Migrate old formats, validate, etc.
+
+  // Before restore — migrate old formats
+  onBeforeRestore: (sessionId, snapshot) => {
+    if (snapshot.version !== "1.0") return migrateSnapshot(snapshot);
+  },
+
+  // After restore
+  onAfterRestore: (session, snapshot) => {
+    console.log(`Restored session ${session.id} at tick ${snapshot.tick}`);
   },
-  onAfterHydrate: (session, snapshot) => { /* ... */ },
+});
+```
+
+#### Restore Layers
+
+**Layer 1 (default):** Snapshot data is auto-applied. Timeline, comState, and dataCache are restored directly. Components see their previous state via `useComState` and `useData`.
+
+**Layer 2 (resolve):** When `resolve` is configured, auto-apply is disabled. Resolve functions control reconstruction and receive the snapshot as context. Results are available via `useResolved(key)`.
+
+```typescript
+const app = createApp(MyApp, {
+  model,
+  sessions: { store: "./sessions.db" },
+
+  // Layer 2: resolve controls reconstruction
+  resolve: {
+    greeting: (ctx) => `Welcome back! You were on tick ${ctx.snapshot?.tick}`,
+    userData: async (ctx) => fetchUser(ctx.sessionId),
+  },
+});
+
+// In components:
+function MyAgent() {
+  const greeting = useResolved<string>("greeting");
+  const userData = useResolved<User>("userData");
+  // ...
+}
+```
+
+#### Context Management vs History
+
+The session's `_timeline` is the append-only historical log — it grows with every message. The `<Timeline>` component controls what the model _sees_ (context) via its props:
+
+```tsx
+// Full history → model context (default)
+<Timeline />
+
+// Only recent messages in context
+<Timeline limit={20} />
+
+// Token-budgeted context
+<Timeline maxTokens={8000} strategy="sliding-window" headroom={500} />
+
+// Role filtering
+<Timeline roles={['user', 'assistant']} />
+```
+
+The `useTimeline()` hook provides direct access for advanced patterns:
+
+```tsx
+function MyAgent() {
+  const timeline = useTimeline();
+
+  // Read current entries
+  console.log(timeline.entries.length);
+
+  // Replace timeline (e.g., after summarization)
+  timeline.set([summaryEntry, ...recentEntries]);
+
+  // Transform timeline
+  timeline.update((entries) => entries.filter((e) => e.message.role !== "system"));
+}
+```
+
+#### `maxTimelineEntries` — OOM Safety Net
+
+For long-running sessions, `maxTimelineEntries` prevents unbounded memory growth by trimming the oldest entries after each tick. This is a safety net, not a context management strategy — use `<Timeline>` props for context control.
+
+```typescript
+const app = createApp(MyApp, {
+  model,
+  maxTimelineEntries: 500, // Keep at most 500 entries in memory
 });
 ```
 
@@ -802,8 +918,8 @@ Apps inherit from the global `Agentick` instance by default:
 import { Agentick, createApp } from "@agentick/core";
 
 // Register global middleware
-Agentick.use('*', loggingMiddleware);
-Agentick.use('tool:*', authMiddleware);
+Agentick.use("*", loggingMiddleware);
+Agentick.use("tool:*", authMiddleware);
 
 // App inherits global middleware (default)
 const app = createApp(MyApp, { model });
@@ -811,7 +927,7 @@ const app = createApp(MyApp, { model });
 // Isolated app (for testing)
 const testApp = createApp(TestApp, {
   model,
-  inheritDefaults: false
+  inheritDefaults: false,
 });
 ```
 
@@ -822,10 +938,10 @@ For one-off executions without session management:
 ```tsx
 import { run } from "@agentick/core";
 
-const result = await run(
-  <MyApp />,
-  { messages: [{ role: "user", content: [{ type: "text", text: "Hello!" }] }], model: myModel }
-);
+const result = await run(<MyApp />, {
+  messages: [{ role: "user", content: [{ type: "text", text: "Hello!" }] }],
+  model: myModel,
+});
 ```
 
 ### Choosing `run()` vs `createApp`
@@ -843,7 +959,79 @@ const result = await run(
 await run(<Agent query="default" />, { props: { query: "override" }, model, messages });
 ```
 
-`createApp` takes a component function and returns a reusable app with session management, hibernation, and middleware support.
+`createApp` takes a component function and returns a reusable app with session management, persistence, and middleware support.
+
+## Execution Environments
+
+An `ExecutionEnvironment` controls the execution backend — how compiled context reaches the model and how tool calls are routed. The default is the standard model → tool_use protocol. Swap in a different environment to change the entire execution model without touching your agent code.
+
+```tsx
+import { createApp, type ExecutionEnvironment } from "@agentick/core";
+
+const replEnvironment: ExecutionEnvironment = {
+  name: "repl",
+
+  // Transform what the model sees — replace tool schemas with prose descriptions,
+  // expose a single "execute" tool, restructure sections, anything.
+  prepareModelInput(compiled, tools) {
+    const commandList = tools
+      .map((t) => `- ${t.metadata?.name}: ${t.metadata?.description}`)
+      .join("\n");
+    return {
+      ...compiled,
+      tools: [executeToolSchema],
+      system: [...compiled.system, { content: `Available commands:\n${commandList}` }],
+    };
+  },
+
+  // Route tool calls — intercept "execute" to a sandbox, let others pass through.
+  async executeToolCall(call, tool, next) {
+    if (call.name === "execute") {
+      return sandbox.run(call.input.code);
+    }
+    return next();
+  },
+
+  // Session lifecycle
+  onSessionInit(session) {
+    sandbox.create(session.id);
+  },
+  onDestroy(session) {
+    sandbox.destroy(session.id);
+  },
+  onPersist(session, snapshot) {
+    return { ...snapshot, comState: { ...snapshot.comState, _sandbox: sandbox.state() } };
+  },
+  onRestore(session, snapshot) {
+    sandbox.restore(snapshot.comState._sandbox);
+  },
+};
+
+// Same agent, different execution model
+const app = createApp(MyAgent, { model, environment: replEnvironment });
+```
+
+The agent's JSX — its `<System>`, `<Timeline>`, `<Tool>` components — stays identical. The environment transforms how that compiled context is consumed and how tool calls execute. This means you can build one agent and run it against multiple backends: standard tool_use for production, a sandboxed REPL for code execution, a human-in-the-loop gateway for approval workflows.
+
+### Interface
+
+All methods are optional. Omitted methods use default behavior.
+
+| Hook                | Purpose                                             | Timing        |
+| ------------------- | --------------------------------------------------- | ------------- |
+| `prepareModelInput` | Transform compiled context before the model sees it | Per tick      |
+| `executeToolCall`   | Intercept, transform, or replace tool execution     | Per tool call |
+| `onSessionInit`     | Set up per-session resources (sandbox, workspace)   | Once          |
+| `onPersist`         | Add environment state to session snapshot           | Per save      |
+| `onRestore`         | Restore environment state from snapshot             | Once          |
+| `onDestroy`         | Clean up resources                                  | Once          |
+
+### Use Cases
+
+- **REPL/Code Execution**: Replace tool schemas with command descriptions, route `execute` calls to a sandboxed runtime, persist sandbox state across sessions.
+- **Human-in-the-Loop**: Transform tool calls into approval requests, gate execution on human confirmation, log decisions.
+- **Sandboxing**: Run tools in isolated containers, inject security boundaries, audit tool invocations.
+- **Testing**: Intercept specific tools to return canned responses, track all lifecycle calls for assertions. See `createTestEnvironment()` in `@agentick/core/testing`.
 
 ## DevTools Integration
 
@@ -867,9 +1055,27 @@ For debugging the reconciler itself with React DevTools:
 import { enableReactDevTools } from "@agentick/core";
 
 // Before creating sessions
-enableReactDevTools();  // Connects to npx react-devtools on port 8097
+enableReactDevTools(); // Connects to npx react-devtools on port 8097
+```
+
+## Local Transport
+
+`createLocalTransport(app)` bridges an in-process `App` to the `ClientTransport` interface. This enables `@agentick/client` (and `@agentick/react` hooks) to work with a local app without any network layer.
+
+```typescript
+import { createApp } from "@agentick/core";
+import { createLocalTransport } from "@agentick/core";
+import { createClient } from "@agentick/client";
+
+const app = createApp(MyAgent, { model });
+const transport = createLocalTransport(app);
+const client = createClient({ baseUrl: "local://", transport });
 ```
 
+The transport is always "connected" — there's no network. `send()` delegates to `app.send()` and streams `SessionExecutionHandle` events as `TransportEventData`. Used by `@agentick/tui` for local agent mode.
+
+See [`packages/shared/src/transport.ts`](../shared/src/transport.ts) for the `ClientTransport` interface.
+
 ## License
 
 MIT