Scope argsSchema docs to the run_factory path and widen the E2E fixture

Enforcement lives behind toolRunFactoryValidateArgs, which the runtime calls
only from runFactoryTool. session.factory.run does not validate, so the docs
and JSDoc now say which caller is checked instead of implying all of them are.

The argument-echo fixture declared ["object","null"] while its contract is to
echo any JsonValue, and it is invoked with an array. Nothing broke, because the
SDK path does not validate, but the narrow declaration was dishonest and would
have become load-bearing if that path ever gained validation. Widened it to the
factory's real contract and corrected the comment, which claimed the fixture
exercised enforcement when it only exercises registration.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MRayermannMSFT

nodejs/docs/factories.md

@@ -52,13 +52,15 @@ Factory metadata contains a stable `name`, a human-readable `description`, decla
 
 ## Declaring an argument shape
 
-A factory that reads `ctx.args` should declare `meta.argsSchema`, as the example above does. The CLI validates the caller's `args` against it **before** the run starts.
+A factory that reads `ctx.args` should declare `meta.argsSchema`, as the example above does. When the model invokes the factory through the `run_factory` tool, the CLI validates `args` against the declaration **before** the run starts.
 
 Declaring one turns an expensive failure into a cheap one. With a schema, a malformed call is rejected up front — the model gets a correction hint and retries, and no run row, permission prompt, or credit spend happens. Without one, nothing validates: the run starts, takes a user approval, spends credits, and then dies inside the factory body with a confusing error. Agents can read the declared shape with `factories_manage` using `operation: "inspect"`.
 
 Enforcement covers structure — types, required properties, and enum or const values. Finer constraints such as `minLength`, `pattern`, or `additionalProperties` are recorded in the declaration but not enforced. The accepted vocabulary is the `FactoryJsonSchema` subset also used for subagent structured output: `type`, `required`, `enum`, `const`, recursive `properties`/`items`, and `anyOf`/`oneOf`/`allOf`. A `type` is one of `null`, `boolean`, `integer`, `number`, `string`, `array`, or `object`, or a non-empty array of those such as `["object", "null"]`. A declaration outside that subset is rejected at registration.
 
-`argsSchema` is optional and backward compatible. A factory that omits it behaves exactly as before, so **the `description` is then the only thing telling an agent what arguments to supply** — state the expected shape there. Arguments supplied by an extension calling `session.factory.run(...)` directly are typed through `defineFactory<TArgs>`, but that typing does not reach the model. A factory that reads `ctx.args` should still validate it rather than assume a shape, because the declared subset does not enforce every constraint.
+`argsSchema` is optional and backward compatible. A factory that omits it behaves exactly as before, so **the `description` is then the only thing telling an agent what arguments to supply** — state the expected shape there.
+
+Validation covers the model's `run_factory` path only. An extension calling `session.factory.run(...)` directly is not validated against `argsSchema`; those arguments are typed through `defineFactory<TArgs>` instead, and that typing does not reach the model. So a factory that reads `ctx.args` should still validate it rather than assume a shape — the declared subset does not enforce every constraint, and it does not run at all on the SDK path.
 
 `defineFactory<TArgs, TResult>` accepts a `run(context)` function returning `Promise<TResult>`, where `TResult` is `JsonValue | void`. Objects, arrays, strings, numbers, booleans, and `null` are valid results. Returning `undefined` completes the factory with no result. Other non-JSON values are rejected.
 

nodejs/src/types.ts

@@ -2011,13 +2011,18 @@ export interface FactoryMeta {
      * Optional declared shape of the arguments this factory expects as `ctx.args`.
      *
      * Declaring one is strongly recommended for any factory that reads `ctx.args`.
-     * The CLI validates the caller's `args` against it **before** the run starts, so a
-     * malformed call from the model is rejected with a correction hint and retried
-     * without ever creating a run row, prompting the user for permission, or spending
-     * credits. A factory that declares nothing is never validated: a malformed call
-     * starts, takes an approval, spends credits, and then fails inside the factory
-     * body. `factories_manage` with `operation: "inspect"` reports the declared shape
-     * so an agent can read it before invoking.
+     * When the model invokes the factory through the `run_factory` tool, the CLI
+     * validates `args` against this declaration **before** the run starts, so a
+     * malformed call is rejected with a correction hint and retried without ever
+     * creating a run row, prompting the user for permission, or spending credits. A
+     * factory that declares nothing is never validated: a malformed call starts,
+     * takes an approval, spends credits, and then fails inside the factory body.
+     * `factories_manage` with `operation: "inspect"` reports the declared shape so an
+     * agent can read it before invoking.
+     *
+     * This covers the model's `run_factory` path only. `session.factory.run(...)` is
+     * not validated against the declaration, so a factory should still check
+     * `ctx.args` rather than assume the declared shape held.
      *
      * Enforcement covers structure — types, required properties, and enum/const
      * values. Finer constraints such as `minLength`, `pattern`, and

nodejs/test/e2e/fixtures/factory-extension.mjs

@@ -18,9 +18,15 @@ const argumentEcho = defineFactory({
         name: "argument-echo",
         description: "Return the invocation arguments verbatim.",
         phases: [],
-        // A declared shape has to survive the SDK boundary and reach the runtime,
-        // which validates `args` against it before a run row exists.
-        argsSchema: { type: ["object", "null"] },
+        // Proves a declared shape survives the SDK boundary and registers against a
+        // real runtime. It does not exercise enforcement: `argsSchema` is checked by
+        // the model's `run_factory` tool, and these tests invoke `session.factory.run`,
+        // which does not validate. The declaration stays as wide as this factory's
+        // actual contract — it echoes any JsonValue, and is called with an array, an
+        // object, and nothing — so it cannot constrain the runs below.
+        argsSchema: {
+            type: ["object", "array", "string", "number", "integer", "boolean", "null"],
+        },
     },
     run: async ({ args }) => args,
 });

nodejs/test/factory.test.ts

@@ -546,6 +546,14 @@ describe("factories", () => {
             );
         }
         expect(normalizeJSDoc(publicTypes)).toContain("before** the run starts");
+        // Enforcement is tool-path only: `toolRunFactoryValidateArgs` is called from
+        // the runtime's runFactoryTool, and never from `session.factory.run`. Both
+        // surfaces must keep saying so, or authors will assume their own SDK-initiated
+        // runs are checked.
+        expect(normalizeJSDoc(publicTypes)).toContain(
+            "`session.factory.run(...)` is not validated against the declaration"
+        );
+        expect(guide).toContain("Validation covers the model's `run_factory` path only");
         expect(normalizeJSDoc(publicApi)).toContain(
             "`null`, `boolean`, `integer`, `number`, `string`, `array`, or `object`"
         );