@agentick/core 0.4.0 → 0.6.0

package/README.md

@@ -309,17 +309,11 @@ function MyComponent() {
   });
 
   // Control agent loop continuation (primary hook for agent behavior)
+  // result.shouldContinue shows framework default; return nothing to defer
   useContinuation((result) => {
-    // Return true to continue, false to stop
-    if (result.text?.includes("<DONE>")) return false;
+    if (result.text?.includes("<DONE>")) return { stop: true, reason: "done" };
     if (result.tick >= 10) return false; // Safety limit
-    return true;
-  });
-
-  // Access COM when needed (always the last parameter)
-  useContinuation((result, ctx) => {
-    ctx.setState("lastTick", result.tick);
-    return !result.text?.includes("<DONE>");
+    // No return = defer to framework (continues if tool calls pending)
   });
 }
 ```
@@ -616,6 +610,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
@@ -983,9 +1010,9 @@ import { createApp, type ExecutionRunner } from "@agentick/core";
 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");
@@ -1031,7 +1058,7 @@ 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 runner state to session snapshot                | Per save      |