[SDK/Factories] Add argsSchema To The Factory Authoring Surface

[MRayermannMSFT]

What

FactoryMeta now declares an optional argsSchema, so an extension author can state the argument shape their factory expects.

It reuses the existing FactoryJsonSchema type. That type already documents the same bounded subset the CLI enforces, and the runtime's own validator points at it as the contract boundary.

The field already crossed the wire, because defineFactory snapshots meta whole rather than cherry-picking fields. This change is additive and type-level. It makes an existing runtime feature discoverable to authors writing against the published types.

Docs and JSDoc now describe what a declaration enforces, matching the run_factory tool description word for word.

Why

Almost no factory declares an argument shape, because the SDK never exposed the field. Authors reading the published types cannot tell the feature exists.

That has a real cost. Without a declared schema nothing validates a caller's args. A malformed call starts a run, takes a user approval, spends credits, and then dies inside the factory body with a confusing error about a missing property.

With a declared schema the CLI catches the mismatch before the run starts. The model gets a correction hint and retries. No run row, no permission prompt, no credit spend.

Notes

• nodejs/src/types.ts is hand-written, not generated. It already imports JsonValue from factory.ts, so importing FactoryJsonSchema alongside it follows the established convention.
• No SDK-side shape validation was added. The runtime already rejects an out-of-subset declaration at registration, and duplicating that logic here would risk divergence.
• argsSchema is optional. A factory that omits it behaves exactly as before, which a unit test asserts.

Testing

• New unit test proves a declared argsSchema survives defineFactory, is deep-frozen, serializes to JSON, and reaches the session.resume registration payload. It also asserts an omitting factory carries no such property.
• New doc test pins the SDK wording to the enforced subset, so the SDK and the run_factory tool cannot drift apart.
• The argument-echo E2E fixture now declares a schema, exercising the field against a live runtime.
• nodejs unit suite, typecheck, lint, and format:check all pass. Three factory.e2e failures are pre-existing and reproduce identically on a clean tree.

[github-actions]

Cross-SDK Consistency Review ✅

This PR adds argsSchema?: FactoryJsonSchema to FactoryMeta in the Node.js SDK.

Scope check: The factory authoring surface (defineFactory, FactoryMeta, FactoryDefinition) only exists in Node.js/TypeScript. The other SDKs (Python, Go, .NET, Java, Rust) contain only generated RPC types for consuming factory run events, not for defining factories. This is an existing intentional asymmetry — there is no define_factory, DefineFactory, or equivalent in the other SDKs.

Verdict: No cross-SDK consistency issues. The change is correctly scoped to the one SDK that exposes the factory authoring API. No updates are needed in the other language SDKs for this PR.

Generated by SDK Consistency Review Agent for #2315 · sonnet46 26.8 AIC · ⌖ 5.37 AIC · ⊞ 6.6K · ◷

[Copilot]

Pull request overview

Exposes factory argument schemas in the Node.js SDK and documents their runtime validation behavior.

Changes:

• Adds optional FactoryMeta.argsSchema.
• Documents supported schema constraints.
• Adds unit and E2E coverage for schema transport.

Show a summary per file

File	Description
nodejs/src/types.ts	Adds the public metadata field.
nodejs/src/factory.ts	Expands schema documentation.
nodejs/docs/factories.md	Documents argument schemas and usage.
nodejs/test/factory.test.ts	Tests freezing, serialization, and documentation.
nodejs/test/e2e/fixtures/factory-extension.mjs	Adds a schema to the E2E fixture.

Review details

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Balanced