feat: add s.path schema helper, improve addon error messages, update docs

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Author: Copilot

README.md

@@ -85,6 +85,8 @@ s.nonEmptyString                    // string with minLength: 1
 s.nonEmptyString("description")
 s.url                               // string with format: "uri"
 s.url("description")
+s.path                              // string with format: "path"; use for file system paths
+s.path("description")
 s.number
 s.integer
 s.int                               // alias for s.integer; prefer for counts, line numbers, integer-only fields

skills/rig/SKILL.md

@@ -92,6 +92,7 @@ Declare a structured agent.
 | `maxTurns` | Retry budget for invalid JSON or invalid output |
 | `addons` | Per-turn addons for steering, validation, and retry customization |
 | `agents` | Optional named subagents exposed to the harness |
+| `tools` | Tool definitions for function-calling (registered via `defineTool`) |
 
 Use `agent({ name, ... })` as the only agent declaration form. `name` is optional; when omitted rig normalizes it to `"agent"`.
 
@@ -140,6 +141,8 @@ s.nonEmptyString                    // string with minLength: 1
 s.nonEmptyString("description")
 s.url                               // string with format: "uri"
 s.url("description")
+s.path                              // string with format: "path"; use for file system paths
+s.path("description")
 s.number
 s.integer
 s.int                               // alias for s.integer
@@ -179,6 +182,7 @@ s.nullable(s.string)    // string | null
 s.literal("done")       // exactly "done"
 s.nonEmptyString        // non-empty string required
 s.url                   // valid URL string
+s.path                  // file system path; prefer over s.string for file/directory inputs
 s.int                   // integer number (no floats); prefer over s.number for counts, line numbers, etc.
 s.nonEmptyArray(s.string)  // string[] with at least one element
 s.nonEmptyObject(s.string) // Record<string, string> with at least one key

skills/rig/rig.ts

@@ -29,7 +29,7 @@
  * T:LauncherIo type {stdin,stdout,stderr} override for launcher subprocess
  * T:JsonSchemaObject type {[key:string]:unknown} plain JSON Schema object
  * s.string/number/integer/boolean/null SchemaHelperFactory primitives; call as value or fn(desc)
- * s.int alias for s.integer; s.nonEmptyString string with minLength:1; s.url string with format:"uri"
+ * s.int alias for s.integer; s.nonEmptyString string with minLength:1; s.url string with format:"uri"; s.path string with format:"path"
  * s.array(items,desc?) ArraySchema; use for homogeneous lists, e.g. s.array(s.string)
  * s.nonEmptyArray(items,desc?) ArraySchema with minItems:1; validates array has at least one element
  * s.object(props,desc?) ObjectSchema; s.optional(inner) marks field optional; s.nullable(inner) accepts inner|null; use for fixed-key shapes
@@ -225,6 +225,8 @@ export const s = {
   nonEmptyString: createConstrainedStringSchema({ minLength: 1 }),
   /** Schema for a URL string (format: "uri"). Call as `s.url` or `s.url("description")`. */
   url: createConstrainedStringSchema({ format: "uri" }),
+  /** Schema for a file system path string (format: "path"). Use instead of `s.string` when the value is a file or directory path; improves readability and hints to the runtime about path-based context resolution. Call as `s.path` or `s.path("description")`. */
+  path: createConstrainedStringSchema({ format: "path" }),
   /** Schema for a `number` value. Call as `s.number` or `s.number("description")`. */
   number: createTypedPrimitiveSchema<NumberSchema>("number"),
   /** Schema for an integer value. Serializes to `{"type":"integer"}` in JSON Schema. Call as `s.integer` or `s.integer("description")`. */
@@ -2052,9 +2054,11 @@ function normalizeAddons(addons?: AgentAddon | AgentAddon[]): AgentAddon[] {
     return [];
   }
   const items = Array.isArray(addons) ? [...addons] : [addons];
-  for (const addon of items) {
+  for (let i = 0; i < items.length; i++) {
+    const addon = items[i];
     if (typeof addon !== "function") {
-      throw new Error("Agent addon entries must be functions.");
+      const got = addon === null ? "null" : typeof addon;
+      throw new Error(`Agent addon entries must be functions (entry at index ${i} is ${got}).`);
     }
   }
   return items;

src/rig.test.ts

@@ -356,7 +356,7 @@ describe("agent invocation", () => {
     });
 
     expect(() => greet.use([null as unknown as any] as any)).toThrow(
-      "Agent addon entries must be functions.",
+      "Agent addon entries must be functions (entry at index 0 is null).",
     );
   });
 
@@ -771,7 +771,7 @@ describe("agent invocation", () => {
     mocks.setSendAndWaitImpl(async () => JSON.stringify("ok"));
     const guarded = agent({ name: "guarded", addons: [null as unknown as any] as any });
     await expect(guarded("go")).rejects.toThrow(
-      "Agent addon entries must be functions.",
+      "Agent addon entries must be functions (entry at index 0 is null).",
     );
   });
 
@@ -1166,6 +1166,8 @@ describe("toJsonSchema", () => {
     expect(toJsonSchema(s.nonEmptyString("A non-empty value"))).toEqual({ type: "string", minLength: 1, description: "A non-empty value" });
     expect(toJsonSchema(s.url)).toEqual({ type: "string", format: "uri" });
     expect(toJsonSchema(s.url("A URL"))).toEqual({ type: "string", format: "uri", description: "A URL" });
+    expect(toJsonSchema(s.path)).toEqual({ type: "string", format: "path" });
+    expect(toJsonSchema(s.path("source path"))).toEqual({ type: "string", format: "path", description: "source path" });
   });
 
   it("includes description when present", () => {
@@ -1365,6 +1367,27 @@ describe("s.url", () => {
   });
 });
 
+describe("s.path", () => {
+  it("serializes to {type:'string', format:'path'}", () => {
+    expect(toJsonSchema(s.path)).toEqual({ type: "string", format: "path" });
+    expect(toJsonSchema(s.path("source file"))).toEqual({ type: "string", format: "path", description: "source file" });
+  });
+
+  it("accepts any string value", () => {
+    const result = analyzeResponse(JSON.stringify("src/index.ts"), s.path, "test", 1);
+    expect(result.ok).toBe(true);
+  });
+
+  it("is usable as an object field", () => {
+    const schema = s.object({ filePath: s.path });
+    expect(toJsonSchema(schema)).toEqual({
+      type: "object",
+      properties: { filePath: { type: "string", format: "path" } },
+      required: ["filePath"],
+    });
+  });
+});
+
 describe("s.null", () => {
   it("serializes to {type:'null'}", () => {
     expect(toJsonSchema(s.null)).toEqual({ type: "null" });