fix(agent): handle nullable JSON Schema type unions in skeletons

.changeset/introspection-nullable-type-union.md

@@ -0,0 +1,8 @@
+---
+"@sapiom/agent": patch
+---
+
+Fix `exampleFromJsonSchema` skeleton generation for JSON Schema `type` unions
+that include `null` (e.g. `{ type: ["string", "null"] }` from Zod `.nullable()`).
+Previously the array form fell through to `null`, so workflow input prefills
+showed `null` instead of a type-appropriate placeholder.

packages/agent/src/introspection.spec.ts

@@ -0,0 +1,44 @@
+import { exampleFromJsonSchema } from "./introspection.js";
+
+describe("exampleFromJsonSchema", () => {
+  it("prefers an author-declared example", () => {
+    expect(
+      exampleFromJsonSchema({
+        type: "string",
+        examples: ["from-author"],
+      }),
+    ).toBe("from-author");
+  });
+
+  it("builds a string skeleton for nullable string types (type union array)", () => {
+    expect(exampleFromJsonSchema({ type: ["string", "null"] })).toBe("");
+  });
+
+  it("builds a number skeleton for nullable number types", () => {
+    expect(exampleFromJsonSchema({ type: ["number", "null"] })).toBe(0);
+  });
+
+  it("builds an integer skeleton for nullable integer types", () => {
+    expect(exampleFromJsonSchema({ type: ["integer", "null"] })).toBe(0);
+  });
+
+  it("builds a boolean skeleton for nullable boolean types", () => {
+    expect(exampleFromJsonSchema({ type: ["boolean", "null"] })).toBe(false);
+  });
+
+  it("returns null when null is the only type in the union", () => {
+    expect(exampleFromJsonSchema({ type: ["null"] })).toBeNull();
+  });
+
+  it("recurses into object properties with nullable scalar fields", () => {
+    expect(
+      exampleFromJsonSchema({
+        type: "object",
+        properties: {
+          name: { type: ["string", "null"] },
+          count: { type: ["integer", "null"] },
+        },
+      }),
+    ).toEqual({ name: "", count: 0 });
+  });
+});

packages/agent/src/introspection.ts

@@ -105,7 +105,11 @@ function skeletonFromJsonSchema(schema: Record<string, unknown>): unknown {
     return skeletonFromJsonSchema(branches[0]);
   }
 
-  switch (schema.type) {
+  const type = Array.isArray(schema.type)
+    ? (schema.type as string[]).find((t) => t !== "null") ?? "null"
+    : schema.type;
+
+  switch (type) {
     case 'object': {
       const props = (schema.properties ?? {}) as Record<string, Record<string, unknown>>;
       const out: Record<string, unknown> = {};