github / github/copilot-sdk

Clarify tool `parameters` JSON Schema validation behavior (depth, location, failure mode)

未关闭
#1,278 2 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
主要语言
Java
星标
10.5k
派生
1.5k
平均合并
1 天 14 小时
30 天内合并 PR
129

描述

### Summary

Where does tool `parameters` JSON Schema validation happen, and how deep does it go? This affects consumer architecture decisions for typed tools that aim to use the schema as the source of truth for input correctness.

### Specific questions

1. **Where does validation happen?** The Node SDK (`nodejs/src/client.ts`) passes `parameters` verbatim to RPC — no client-side validation, no JSON Schema validator imported. Validation, if any, must happen in the CLI binary or at the model layer. **Where exactly?**

2. **How deep does it go?** For a schema like:
```json
{
"type": "object",
"required": ["topIssues", "summary"],
"additionalProperties": false,
"properties": {
"topIssues": {
"type": "array",
"items": { "type": "object", "required": ["issueId", "severity"], "properties": {} }
},
"summary": { "type": "string" }
}
}
```
Does the runtime reject:
- Wrong top-level key? (`{top_issues: [...]}` instead of `{topIssues: [...]}`)
- Missing top-level required field? (`{topIssues: [...]}` missing `summary`)
- Extra top-level key when `additionalProperties: false`?
- **Wrong item-level shape?** (`topIssues: [{title: "foo"}]` — missing required `issueId` and `severity`)
- Wrong nested type?

3. **What happens on failure?** Does the orchestrator get re-prompted with the validation error so it can self-correct? Or does the tool call just fail silently? The `TaskCompleteData.success` field has a comment "False when validation failed (e.g., invalid arguments)" suggesting validation surfaces somewhere, but the consumer-visible behavior isn't documented.

### Why this matters

Consumers migrating from generic `writeArtifact({path, content: "..."})` patterns to typed tools depend on what the boundary enforces. If item-level shape IS validated, the LLM physically cannot return a malformed inner structure. If it isn't, handler-side item-level checks remain necessary and the "typed tool" claim is partial.

For us specifically: we have ~6 LLM-driven agents currently writing terminal artifacts through a generic `writeArtifact` shape, with schema living only in the prompt. We see ~30-40% drift to wrong shapes (snake_case vs camelCase, renamed wrappers, etc.) which costs $15-30 per wasted phase. Migrating to typed phase tools is on the roadmap; the value of that migration depends on the answers above.

### Evidence (SDK source — partial answer)

`nodejs/src/client.ts`: tool parameters are converted via `toJsonSchema()` (which calls `parameters.toJSONSchema()` for Zod schemas or passes JSON Schema objects through unchanged). No client-side validation. No JSON Schema validator (ajv, zod-validate, etc.) is imported.

**Confirmed:** the Node SDK does no validation. Validation, if any, is entirely in the CLI binary (which is not source-readable).

### What we'd like

A docs page or release note clarifying: (a) where validation happens (SDK / CLI / model layer), (b) what shape it covers (top-level only / item-level / arbitrarily deep), (c) what happens on failure (re-prompt / silent / error).

If item-level isn't validated today, that promotes this from a question to a feature request: **deep JSON Schema enforcement against `parameters`**.

### Environment

```
- SDK: @github/copilot-sdk@0.3.0
- CLI: @github/copilot@1.0.45
- Node: 22 LTS
- OS: Windows 11
- Model: claude-sonnet-4-6
```

贡献指南

打开贡献指南

调研方向

从 nodejs/src/client.ts 开始,跟踪参数是如何转换并传递给 RPC 的;查看 TaskCompleteData.success 的注释,将其作为已记录的失败线索。验证 CLI 或模型层对嵌套验证和失败的行为,然后在文档页面或发布说明中记录验证位置、验证深度以及消费者可见的结果。

由索引模型根据 Issue 内容生成。

评估

技术栈
nodejs
领域
api, documentation
Issue 类型
文档
难度
4/5
预计耗时
3-5 天
活跃度
冷清
描述清晰度
基本清楚
新手友好度
45/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。