Port pydantic-ai v1.103.0: PreparedToolset nullish-prepare warning + version parity update

.github/pydantic-ai-version.txt

@@ -1 +1 @@
-1.87.0
+1.103.0

packages/sdk/docs/reference/features.mdx

@@ -84,6 +84,7 @@ Vibes is designed to stay current with Pydantic AI  -  an AI agent automatically
 | Toolset reuse             | Share toolsets across agents                | ✅     | [Toolsets](/concepts/toolsets) | `Toolset` is a plain interface - pass the same instance to multiple agents |
 | Runtime swap              | Replace toolsets during testing             | ✅     | [Testing](/concepts/testing) | `agent.override({ toolsets: [...] }).run(prompt)` |
 | `PreparedToolset`         | Modify entire tool list before each step    | ✅     | [Toolsets](/concepts/toolsets) | `new PreparedToolset(inner, (ctx, tools) => tools)` - dynamic per-turn |
+| Prepare callback warning  | Warn when `prepare` callback returns `None` (v1.103.0) | ✅ | [Toolsets](/concepts/toolsets) | `PreparedToolset` logs a warning and falls back to inner tools on `null`/`undefined` |
 | `ApprovalRequiredToolset` | Enforce human approval on a toolset         | ✅     | [Human-in-the-Loop](/concepts/human-in-the-loop) | `new ApprovalRequiredToolset(inner)` - all tools get `requiresApproval` |
 | `WrapperToolset`          | Custom execution behaviour around a toolset | ✅     | [Toolsets](/concepts/toolsets) | `class MyWrapper extends WrapperToolset { callTool(...) { ... } }` |
 | `ExternalToolset`         | Deferred execution outside agent process    | ✅     | [Human-in-the-Loop](/concepts/human-in-the-loop) | `new ExternalToolset([{ name, description, jsonSchema }])` - schema-only |

packages/sdk/lib/toolsets/prepared_toolset.ts

@@ -42,6 +42,13 @@ export class PreparedToolset<TDeps = undefined> implements Toolset<TDeps> {
 
   async tools(ctx: RunContext<TDeps>): Promise<ToolDefinition<TDeps>[]> {
     const innerTools = await this._inner.tools(ctx);
-    return this._prepare(ctx, innerTools);
+    const preparedTools = await this._prepare(ctx, innerTools);
+    if (preparedTools === null || preparedTools === undefined) {
+      console.warn(
+        "PreparedToolset.prepare returned null/undefined; falling back to inner tools.",
+      );
+      return innerTools;
+    }
+    return preparedTools;
   }
 }

packages/sdk/tests/prepared_toolset_test.ts

@@ -179,3 +179,33 @@ Deno.test("PreparedToolset - prepare called on every turn", async () => {
   // called at least twice.
   assertEquals(prepareCallCount >= 2, true);
 });
+
+Deno.test("PreparedToolset - warns and falls back when prepare returns nullish", async () => {
+  let capturedNames: string[] = [];
+  let warning: string | undefined;
+  const originalWarn = console.warn;
+  console.warn = (...args: unknown[]) => {
+    warning = args.map(String).join(" ");
+  };
+  try {
+    const model = new MockLanguageModelV3({
+      doGenerate: (opts) => {
+        capturedNames = toolNames(opts);
+        return Promise.resolve(textResponse("done"));
+      },
+    });
+
+    const inner = new FunctionToolset([makeTool("fallback_tool")]);
+    const prepared = new PreparedToolset(
+      inner,
+      () => undefined as unknown as import("../mod.ts").ToolDefinition[],
+    );
+    const agent = new Agent({ model, toolsets: [prepared] });
+    await agent.run("go");
+
+    assertEquals(capturedNames.includes("fallback_tool"), true);
+    assertEquals(warning?.includes("PreparedToolset.prepare returned null/undefined"), true);
+  } finally {
+    console.warn = originalWarn;
+  }
+});