Move the last hint parameter overlays into in-code ParamDecls (helpers +
shortcuts), regenerate catalog, and harden the migrate script for factory
and Use/RPC matching so all 74 overlay tools are declaration-backed.
Co-authored-by: Cursor <cursoragent@cursor.com>
Move 121/210 parameter-level Schema field overlays from
schema_hints/metadata JSON into in-code ParamDecl declarations on
DeclareLeafMetadata commands. The declared values are emitted as
dws.schema.* annotations at assembly time via ApplyParamDecls,
outranking tool_schema_hint (rank 620 > 500) so the hint overlay
becomes redundant once the declaration is in place.
Key mechanism changes:
- Add SchemaDecl.Parameters []ParamDecl with property/required/
interface_type/description/required_when/enum fields
- Add cli.ParamDecl type carried inside ContractFinalPayload
- ApplyParamDecls emits dws.schema.* annotations from the payload
at assembly time (no sync.Map, no tree-rebuild key issue)
- Add cli.AnnotateRuntimeFlagInterfaceType (41 overlays needed it)
- Add cli.AnnotateRuntimeFlagRequiredValue for explicit true/false
- Compatibility alias check tolerates dws.schema.* annotation
differences between primary and alias commands
- Remove runtime source_hash recomputation (87ms/997k allocs saved;
enforced by check-generated-drift.sh at build time instead)
- Add shortcut.Flag.RequiredWhen and wire through FromShortcut
- Add boolFlag OR semantics to fix confirmationBypass disagreement
- Add bindKey default kebab-to-camel for forgotten Bind
- Add schema consumption benchmarks (catalog decode 1.5s/817MB,
shortcut load 1.9ms/3MB — three orders of magnitude apart)
- Add catalog codegen feasibility probe (34 tools: 0.06s compile,
31ns access, 87KB linked — extrapolates to 2.1MB for 845 tools)
Migrated products (29 tools, 121 fields):
aisearch(1), chat(12), contact(4), doc(3), drive(1),
hrbrain(10), mail(2), report(1), sheet(3), todo(6)
Remaining 89 fields across 11 products blocked by:
- RPCName not found as string literal (19 tools, shortcut/variable)
- No matching DeclareLeafMetadata near callMCPTool (11 tools)
- No single RPCName for multi-step commands (drive.upload etc.)
All tests green: corecmd, cli, helpers. Generation and drift clean.
The ContractFinal assembly path dropped every non-declared parameter fact,
breaking the published Schema against the reviewed merge-base contract:
- merge pinned MCP parameter metadata and the reviewed in-code runtime hints
back into contract_final parameter resolution (318 interface_type losses,
calendar recurrence required/required_when regressions)
- restore devapp write risk to high and publish back to write/high; the
migration silently downgraded 14 dev write tools and re-classified publish
as destructive
- keep dev at-least-one checks as Validate hooks with the shipped wording
instead of publishing new typed constraints; constraint publication is a
contract change that belongs to its own reviewed PR (aitable annotations
reverted for the same reason)
- align RunE escape hatch, BoolFlag shadowing, guard-first ConfirmFirst
declaration, and Sheet target preflight with behavioral tests; drop the
retired gen_schema_decls.py helper and fix corecmd naming in docs/CHANGELOG
check-authoritative-schema-compatibility vs origin/main: ok.
PreRunE Validate was skipped by direct RunE / proxy calls. Run both hooks
in one wrapper (Validate first), add pat chmod Validate, let Sheet outer
guards call ContractValidate first, and assert declare user_required
leaves expose Validate, required flags, or CallTool-defer confirm.
Co-authored-by: Cursor <cursoragent@cursor.com>
DeclareLeafMetadata user_required wraps were confirming before RunE-local
checks, so illegal calls got confirmation_required instead of real errors.
Allow Validate on PreRunE, migrate event stop and drive publish checks, and
lock the Sheet dual-gate transitional state.
Co-authored-by: Cursor <cursoragent@cursor.com>
Compile reviewed Agent Schema into bind-time Go declarations so catalog
tools stamp contract_final without changing execution bodies.
Co-authored-by: Cursor <cursoragent@cursor.com>
Align the write-confirmation UX with lark-cli: ConfirmRisk (and the
shortcut confirmRisk) now print the yes/no prompt only when stdin is a
real terminal (ioctl-level check via go-isatty; a char-device stat would
misclassify `< /dev/null`). Non-interactive callers get a clean
structured confirmation_required error on stderr. Piped answers are
still honored for humans/scripts; --yes/--dry-run remain the sanctioned
non-interactive paths.
skills/mono: add the recognition + retry protocol for agents —
identify confirmation_required via error.reason, show action and params,
retry the original command with --yes only after explicit user consent,
never silently append --yes or treat it as a transient error.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Alignment-only changes in runtime_schema.go, schema_contract_model.go,
and devapp_safety_homology_test.go. Remaining make lint findings are in
upstream-owned keychain/transport files untouched by this PR.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Upstream added five reviewed tools (845 total); hashes and counts
refresh. Content of existing tools is unchanged.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Risk (runtime confirmation) and Safety (schema metadata) are two
independent enums composed at embed time: explicit SafetyDecl fields >
CommandSpec.Safety tier > Risk.SafetyDefault(). The tier fill now also
covers idempotency, so an enum-only declaration is self-sufficient and
validateSchemaDecl no longer needs safety completeness checks.
devapp reclassifies its write leaves by reversibility: reversible
mutations declare LeafSafetyWrite (risk high->medium), create/robot
submit/version create declare LeafSafetyHighWrite, and delete/version
publish declare LeafSafetyDestructive (publish effect
write->destructive). Shared hand-written safety constants are deleted.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
- validateSchemaDecl now also requires Safety (effect/risk/confirmation
or the Risk shorthand; Idempotency is declaration-only) and Interface
(mode/availability, plus reason for composite/unavailable), so every
unconditional catalog required key is guaranteed at construction time
- declared dry_run capabilities are indexed by BindEffectiveCommandRegistry
instead of Schema assembly: every process resolving the command tree
gets the reviewed set, removing the hidden "must assemble in-process
first" precondition of the delivery gate
- agent-metadata contract merge now errors when a declared tool has no
canonical CLI projection instead of silently dropping the declaration
Artifacts are byte-identical; full cli/cmdcore/helpers/generator suites pass.
Co-authored-by: Cursor <cursoragent@cursor.com>
- dry_run capabilities declared via cmdcore.SchemaDecl are reviewed by
construction: the Schema pass-through indexes them into the reviewed
capability set, so declared tools no longer need manual entries in
reviewedDryRunCapabilityGroups (31 devapp paths deleted). A conflicting
manual entry for the same canonical is a hard error.
- NewCommand now enforces authoring-time homology for declared commands:
a non-empty Schema without Description/AgentSummary/UseWhen/AvoidWhen/
Examples panics at construction instead of failing later in generated
artifacts or silently drifting from cobra prose.
- --help Example inherits Schema.Selection.Examples when not authored
separately, keeping one authored source for examples.
Catalog and agent metadata artifacts are byte-identical.
Co-authored-by: Cursor <cursoragent@cursor.com>
The agent-metadata generator now merges each registered Contract final
overlay (cmdcore.SchemaDecl) as the top-precedence contract_final
candidate, so declared tools no longer need hint-file rows for
agent_summary/use_when/avoid_when/examples/safety/interface. Selection
eval fixtures and example execution plans synthesize the same assertions
from the declaration, keeping semantic-eval and example coverage intact.
- devapp hint rows deleted from schema_hints/{metadata,selection}/dev.json
(connect_status/connect_stop/search_open_platform_docs_rag kept);
artifact content for all 31 declared leaves is byte-identical, only
provenance now reads contract_final / cmdcore.SchemaDecl
- exact-coverage gates exempt declared tools (hints remain required for
every non-declared command); reviewed-delivery gate accepts
contract_final as the stronger reviewed source
- cmdcore derives effect_source=cmdcore.contract for SchemaDecl-only
safety (read leaves), matching the Risk-shorthand path
Co-authored-by: Cursor <cursoragent@cursor.com>
Every devapp leaf now declares its full final Schema in LeafSpec
(description/safety/interface/selection/dry_run plus Risk, Required
flags and at-least-one Constraints); declaration is the sole final
source, hints no longer shape the published catalog for these tools.
- Hand-written delete/robot submit/robot config migrate to
LeafSpec+RunE with manual cmdcore.ConfirmRisk; robot result becomes
a plain declared leaf. Legacy write guard, runtime_gate annotation
and now-dead helpers are removed; the homology gate is strengthened
to declare-only for the devapp tree.
- New CommandSpec/LeafSpec ConfirmFirst knob reproduces the devapp
guard-first semantics (confirmation_required before parameter
validation) without changing shortcut ordering.
- dry_run is published for all 31 leaves via the reviewed capability
registry (invocation preview, no remote reads).
- Catalog regenerated: dry_run blocks added, unified-app-id/
version-id/member-type/user-ids correctly marked required,
require_one_of constraints published for get/webapp config/security
config, and robot config name corrected to optional (CLI upsert
runtime truth; the remote schema's required was not CLI-accurate).
Co-authored-by: Cursor <cursoragent@cursor.com>
- SchemaDecl on CommandSpec/LeafSpec declares the final ToolSpec payload;
framework converts in-process (no JSON bridge) and Schema assembly
pass-throughs it.
- Assembly fails closed on declared identity mismatched with the bound
entry and on reviewed fields in the declaration payload.
- RFC/homology/AGENTS docs pin declare=final-source, safety precedence
Final > Risk > gate, and light runtime write semantics.
Co-authored-by: Cursor <cursoragent@cursor.com>
Must-fix: drive permission apply now gates on confirmDangerousAction and
declares confirmation=user_required, matching its help-text promise.
Wukong parity restored: formula-verify --exit-on-error (payload-parsing
exit path) and --targets conflict error, sheet info --include, chat
location/profile message types, search-advanced wukong flag aliases,
and a dedicated drive download-version leaf replacing the removed
polymorphic download --version.
Consistency fixes: transfer-owner --node/--workspace XOR and JSON-aware
dry-run after --yes validation; drive list --versions rejects
--depth/--pattern instead of misleading depth errors; depth BFS resumes
rate-limited folders from the failed page cursor to avoid duplicates;
doc style cover upload honors cmd.Context() and a 20 MiB size cap; chat
user-settings set validates per-item openConversationId and is
risk=medium.
Hardened the skill static audit to scan fenced code blocks and reject
unknown subcommands on group commands, fixing the stale aitable/drive
doc examples it exposed. Added CHANGELOG entry and coverage tests for
all changed statements plus previously untested ported commands.
The 26 newly registered commands raised the registry count to 839, but
runtime-surface-completeness.json still declared source_tools=813, so
check-schema-catalog.sh failed the Policy job ("runtime-surface
completeness source must remain unreviewed and interface-free"). The 26
tools are all reviewed in metadata/selection sources, so the unreviewed
71-tool list is unchanged; regenerate dependent schema artifacts.
- Port drive list --depth N BFS recursive listing (pan + workspace routes,
rate-limit requeue, SIGINT partial emit, --pattern/--quiet)
- Port doc style cover set/clear, background set/clear, get with local
image validation and attachment-upload subflow
- Register all 26 newly ported commands in schema_command_registry with
reviewed metadata/selection hints instead of exclusions (813->839 tools)
- Review fixes: drive list --node usage text no longer implies required
in agent schema; remove broken formula-verify --exit-on-error; error on
--range without --sheet-id; portable stdin read; drop local --yes
shadowing root -y on drive revert/transfer-owner; use
confirmDangerousAction for non-delete confirms; explicit
recursiveChange=false now transmitted; sheet version revert and
comment delete moved into sheet confirmationGuards registry
Remove --version flag from drive download (polymorphic tool dispatch
incompatible with schema validation). Regenerate schema catalog and
add new commands to schema_command_exclusions.json.
