feat(agent-cli): validate tool input against the declared schema

[ScriptedAlchemy]

Summary

Both tool executors (createRsdoctorCliToolExecutor and createInProcessRsdoctorCliToolExecutor) validate each invocation against the tool's declared JSON Schema before dispatch, throwing a structured ToolInputValidationError instead of forwarding unchecked input to handlers.

• Ajv compiles and caches validators rather than maintaining a partial JSON Schema interpreter.
• Catalog schemas merge each tool's options with shared page, pageNumber, pageSize, and limit controls.
• Unknown properties are rejected for strict catalog tools.
• Required fields, enum values, numeric bounds, arrays, nested values, and standard JSON Schema constraints are validated consistently by both executors.
• Numeric strings remain supported only for numeric fields, preserving existing CLI/control behavior without broader type coercion.
• pageNumber and limit remain supported aliases and are normalized before handler dispatch.
• Validation failures collect { path, message } issues and prevent the command from running.
• ToolInputValidationError is exported for programmatic consumers.

This PR is intentionally stacked on the artifact and bounded-output work in #1903 so its pkg.pr.new preview represents the exact contract consumed by Rstack Context.

Verification

• Agent CLI tests: 67 passed
• Agent CLI build and type-check passed
• Repository lint and dependency-version checks passed
• Built entry: 118.4 kB (120.4 kB baseline before the Ajv refactor)

Related Links

• Base PR: feat(core): add versioned artifact metadata #1903
• Context consumer: feat: establish standalone Rstack context runtime rstackjs/context#1
• Rstack CLI integration: feat(context): add the Rstack context engine rstackjs/rstack-cli#344

[pkg-pr-new]

@rsdoctor/agent-cli

npm i https://pkg.pr.new/@rsdoctor/agent-cli@1924

@rsdoctor/cli

npm i https://pkg.pr.new/@rsdoctor/cli@1924

@rsdoctor/client

npm i https://pkg.pr.new/@rsdoctor/client@1924

@rsdoctor/core

npm i https://pkg.pr.new/@rsdoctor/core@1924

@rsdoctor/shared

npm i https://pkg.pr.new/@rsdoctor/shared@1924

commit: 8926633

[cloudflare-workers-and-pages]

Deploying rsdoctor-v1 with    Cloudflare Pages

Latest commit:	760f88e
Status:	✅  Deploy successful!
Preview URL:	https://539a4bc5.rsdoctor-v1.pages.dev
Branch Preview URL:	https://codex-agent-cli-input-valida.rsdoctor-v1.pages.dev

View logs

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9844ebd305

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds executor-side input validation for @rsdoctor/agent-cli tools, ensuring tool invocations are checked against their declared inputSchema before dispatch and surfacing structured validation errors to programmatic consumers.

Changes:

• Introduces validateToolInput + ToolInputValidationError to validate tool inputs and report aggregated issues.
• Hooks validation into both the spawned-CLI and in-process tool executors.
• Adds comprehensive unit tests covering validation success/failure cases across both executor paths and exports validation utilities from the package entry.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/agent-cli/src/core/validate-input.ts	Implements schema-based input validation and a structured error type.
packages/agent-cli/src/executor.ts	Validates tool input before dispatch for both executor implementations.
packages/agent-cli/src/commands/router.ts	Ensures in-process tool entries carry the same inputSchema as the catalog.
packages/agent-cli/src/index.ts	Exposes validation exports from the package public API.
packages/agent-cli/tests/tool-input-validation.test.ts	Adds tests for validation behavior (types, required, bounds, enums, arrays, aggregation, both executors).

Suppressed comments (2)

packages/agent-cli/src/core/validate-input.ts:74

• Similar to integer, number validation currently rejects numeric strings, which makes validation stricter than CLI/control parsing and can break programmatic callers that pass stringified numbers (common when values originate from argv/env/JSON).

    case 'number':
      return typeof value === 'number' && Number.isFinite(value);

packages/agent-cli/src/core/validate-input.ts:145

• Numeric bounds (minimum/maximum) are only enforced when the value is a JS number. If numeric strings are accepted for integer/number (as per CLI/control parsing), bounds should be checked against the coerced numeric value as well; otherwise values like '5000' would bypass maximum checks.

  if (typeof value === 'number') {
    if (typeof schema.minimum === 'number' && value < schema.minimum) {
      issues.push({
        path,
        message: `${label} must be >= ${schema.minimum}, received ${value}`,

---

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

[cloudflare-workers-and-pages]

Deploying rsdoctor with    Cloudflare Pages

Latest commit:	760f88e
Status:	✅  Deploy successful!
Preview URL:	https://e8f9be91.rsdoctor.pages.dev
Branch Preview URL:	https://codex-agent-cli-input-valida.rsdoctor.pages.dev

View logs