feat(ai): get_metadata_schema — let the AI read a type's contract before authoring#1561
Merged
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
…contract The authoring agent never sees the real spec Zod schemas; it guesses the shape of complex types (view/dashboard/flow) and learns from validation errors. New get_metadata_schema returns the JSON Schema (Zod v4 toJSONSchema) derived from the same getMetadataTypeSchema the write path validates against, and the metadata_authoring skill tells the agent to consult it before authoring a non-trivial type. Read-only; plural-tolerant; graceful error for non- serializable types (object — covered by create_object anyway). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
xuyushun441-sys
force-pushed
the
feat/get-metadata-schema-tool
branch
from
7504959 to
35ce6f3
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Follows the discussion of why the AI generated an invalid kanban view (#1559). Root cause: the authoring agent never sees the real spec Zod schemas. It works against a simplified blueprint or sends a free-form
definition, and only learns the true shape from post-hoc validation errors. For complex types (viewis 500+ lines, plusdashboard/flow/…) that means guessing — e.g. a kanban view's requiredkanban: { groupByField, columns }block.Letting the runtime agent read the spec source folder isn't the answer (source isn't present at runtime — only compiled dist; it's an end-user-facing sandboxed agent without a filesystem tool; raw Zod is the wrong format). The right move is to serve the schema it already validates against.
What
New
get_metadata_schematool: returns the JSON Schema for a metadata type, derived (Zod v4toJSONSchema) from the SAMEgetMetadataTypeSchema(type)the write path (saveMetaItem) validates against. The agent can read the exact contract and author a correct payload in one shot instead of trial-and-error.metadata_authoringskill instructs the agent to call it before authoring a non-trivial type (kanban block as worked example).Covers ALL app-development metadata types
Naively,
objectandactionthrow inside Zod v4'stoJSONSchemabecause their schemas wrap/nest a.transform()/refine pipe (e.g. an object'sactions: z.array(ActionSchema)). The handler uses a robust converter that peels pipes to their input side (io:'input') and, if whole-schema conversion still fails, recurses property-by-property / element-by-element — so every app-dev type yields a usable contract: object, field, view, page, dashboard, report, app, flow, action, agent, role, … (a genuinely unrepresentable leaf degrades to a placeholder rather than failing the whole call).Tests
metadata-tools: returns a JSON-Schema-shaped contract forview, plural→singular resolution, graceful unknown-type error, and a sweep asserting all 11 core app-dev types serialize (object/action included). service-ai metadata + blueprint suites green (146).🤖 Generated with Claude Code