@agentick/core 0.3.0 → 0.5.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 (
@@ -604,6 +616,39 @@ function App() {
 }
 ```
 
+### Prop Overrides
+
+Customize pre-built tool metadata via JSX props without creating new tools:
+
+```tsx
+<WeatherTool description="Check weather. Always include units." />
+<ShellTool name="bash" requiresConfirmation={true} />
+```
+
+### Tool Sources
+
+Tools merge from four sources (lowest → highest priority):
+
+```tsx
+// 1. App-level — available to all sessions
+const app = createApp(Agent, { tools: [SearchTool] });
+
+// 2. Session-level — available for this session
+const session = await app.session({ tools: [FileTool] });
+
+// 3. Per-execution — available only during this send()
+await session.send({ messages: [...], tools: [DynamicTool] });
+
+// 4. JSX-reconciled — highest priority, re-evaluated each tick
+function Agent() {
+  return <SearchTool description="Custom desc" />;
+}
+```
+
+On each tick, tools merge in order: app → session → execution → JSX. Last-in wins by name.
+
+Spawned sessions (`session.spawn()`) start fresh — they do **not** inherit parent tools. Each child defines its own toolset via JSX and app-level tools.
+
 ## App & Session
 
 ### Creating an App
@@ -626,7 +671,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)
+  runner: myRunner,            // Execution runner (see below)
 });
 ```
 
@@ -961,19 +1006,19 @@ await run(<Agent query="default" />, { props: { query: "override" }, model, mess
 
 `createApp` takes a component function and returns a reusable app with session management, persistence, and middleware support.
 
-## Execution Environments
+## Execution Runners
 
-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.
+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 ExecutionEnvironment } from "@agentick/core";
+import { createApp, type ExecutionRunner } from "@agentick/core";
 
-const replEnvironment: ExecutionEnvironment = {
+const replRunner: ExecutionRunner = {
   name: "repl",
 
-  // Transform what the model sees — replace tool schemas with prose descriptions,
+  // Transform the compiled structure — replace tool schemas with prose descriptions,
   // expose a single "execute" tool, restructure sections, anything.
-  prepareModelInput(compiled, tools) {
+  transformCompiled(compiled, tools) {
     const commandList = tools
       .map((t) => `- ${t.metadata?.name}: ${t.metadata?.description}`)
       .join("\n");
@@ -1008,10 +1053,10 @@ const replEnvironment: ExecutionEnvironment = {
 };
 
 // Same agent, different execution model
-const app = createApp(MyAgent, { model, environment: replEnvironment });
+const app = createApp(MyAgent, { model, runner: replRunner });
 ```
 
-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.
+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
 
@@ -1019,11 +1064,11 @@ All methods are optional. Omitted methods use default behavior.
 
 | Hook                | Purpose                                             | Timing        |
 | ------------------- | --------------------------------------------------- | ------------- |
-| `prepareModelInput` | Transform compiled context before the model sees it | Per tick      |
+| `transformCompiled` | 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          |
+| `onPersist`         | Add runner state to session snapshot                | Per save      |
+| `onRestore`         | Restore runner state from snapshot                  | Once          |
 | `onDestroy`         | Clean up resources                                  | Once          |
 
 ### Use Cases
@@ -1031,7 +1076,7 @@ All methods are optional. Omitted methods use default behavior.
 - **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`.
+- **Testing**: Intercept specific tools to return canned responses, track all lifecycle calls for assertions. See `createTestRunner()` in `@agentick/core/testing`.
 
 ## DevTools Integration