@agentick/core 0.2.1 → 0.4.0

package/README.md

@@ -592,6 +592,18 @@ const WeatherTool = createTool({
   render: (tickState, ctx) => <Section id="weather-info">Last checked: {lastChecked}</Section>,
 });
 
+// Tools can capture tree-scoped context via use():
+const ShellTool = createTool({
+  name: "shell",
+  description: "Execute a command in the sandbox",
+  input: z.object({ command: z.string() }),
+  use: () => ({ sandbox: useSandbox() }), // runs at render time
+  handler: async ({ command }, deps) => {
+    const result = await deps!.sandbox.exec(command);
+    return [{ type: "text", text: result.stdout }];
+  },
+});
+
 // Use in your app
 function App() {
   return (
@@ -626,6 +638,7 @@ const app = createApp(MyApp, {
   devTools: true,              // Enable DevTools emission
   tools: [ExternalTool],       // Additional tools (merged with JSX <Tool>s)
   mcpServers: { ... },         // MCP server configs
+  runner: myRunner,            // Execution runner (see below)
 });
 ```
 
@@ -741,43 +754,139 @@ 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
   },
+});
+```
 
-  // Session lifecycle hooks
-  onSessionCreate: (session) => {
-    /* ... */
-  },
-  onSessionClose: (sessionId) => {
-    /* ... */
+**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
+
+#### Snapshot Contents
+
+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
   },
 
-  // Hibernation hooks
-  onBeforeHibernate: (session, snapshot) => {
-    // Return false to cancel, modified snapshot, or void
-    if (session.inspect().lastToolCalls.length > 0) return false;
+  // After save
+  onAfterPersist: (sessionId, snapshot) => {
+    console.log(`Saved session ${sessionId}`);
   },
-  onAfterHibernate: (sessionId, snapshot) => {
-    /* ... */
+
+  // Before restore — migrate old formats
+  onBeforeRestore: (sessionId, snapshot) => {
+    if (snapshot.version !== "1.0") return migrateSnapshot(snapshot);
   },
-  onBeforeHydrate: (sessionId, snapshot) => {
-    // Migrate old formats, validate, etc.
+
+  // 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
+});
 ```
 
 ### Procedures & Middleware
@@ -862,7 +971,79 @@ const result = await run(<MyApp />, {
 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 Runners
+
+An `ExecutionRunner` 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 runner to change the entire execution model without touching your agent code.
+
+```tsx
+import { createApp, type ExecutionRunner } from "@agentick/core";
+
+const replRunner: ExecutionRunner = {
+  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, runner: replRunner });
+```
+
+The agent's JSX — its `<System>`, `<Timeline>`, `<Tool>` components — stays identical. The runner 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 runner state to session snapshot                | Per save      |
+| `onRestore`         | Restore runner 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 `createTestRunner()` in `@agentick/core/testing`.
 
 ## DevTools Integration
 
@@ -889,6 +1070,24 @@ import { enableReactDevTools } from "@agentick/core";
 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