Skip to content

fix(mcp): let dashboard_write clear an object field with clear: true - #20241

Merged
iamwhatever merged 2 commits into
mainfrom
fix/dashboard-write-object-clear-20089
Oct 15, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
fix/dashboard-write-object-clear-20089

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let dashboard_write with clear: true empty an object field by writing {} instead of always writing [].

When clear: true is passed to dashboard_write, the handler always wrote []. For object fields (asks, drafts, steps), the gateway refused that write with wrong_type, left the field unchanged, and added a wrong_type entry to the mistake book. The only way to clear an object field was to pass value: {} directly, but an MCP client drops value: {} before it reaches the server.

This is part 2 of #20089; part 1 is #20144.

Why it matters

An agent tracking answered goal-board questions has no way to clear asks once it is empty -- every clear: true call fails with a gateway error and teaches the model the wrong spelling. The mistake book entry then re-appears on the next read, causing the agent to keep retrying a write that will never succeed.

Not a goal

  • Changing the gateway write route or DASHBOARD_WRITE_SCHEMA
  • Handling field types other than array and object with clear (string, number, boolean are now refused at the panel layer with a clear message)
  • Changing behavior for calls that pass a value

What changed

Root cause: _call_tool_inner hardcoded to_write = [] for every clear: true call, regardless of the field's declared type.

Fix: added _empty_value_for(field, sk), which reads the field list from /api/agent-panel/dashboard/fields (the same route dashboard_fields uses) and returns {} for an object field and [] for any other field. The panel server does not refuse a clear for the field's type or source: a string, number or boolean field, a fold-sourced field and an unknown field all go to the write route, which refuses them with wrong_type, field_not_agentic or unknown_field and records the refusal in the mistake book. If the field list cannot be read (the GET fails or returns no list), the server writes []. The tool description and clear parameter description are updated to say "array or object field". validation.py now accepts value: {} beside clear: true (redundant but unambiguous), and its error text and the DASHBOARD_WRITE_TOOL_SCHEMA comment are updated. The owning spec, docs/system-specs/modules/dashboard-instances.md, describes the same behaviour.

Correction to "Not a goal": its second bullet says string, number and boolean fields "are now refused at the panel layer with a clear message". That described an earlier revision of this PR. In the code as it stands, those fields reach the write route and are refused there, as described above. The Goal, Why it matters and Not a goal sections stay as written when the PR opened, so the correction is recorded here.

Backwards compatibility

Compatible: no call that works today stops working. Calls with value are unchanged. Calls without value and without clear are unchanged. Calls with clear: true on array fields still get [] (the field list confirms the type). If the field type cannot be read, clear: true writes [], as it did before this PR, so clearing an array field does not depend on the fields route; each clear makes one extra GET to that route before the write. clear: true on an object field now succeeds instead of failing, and value: {} beside clear: true is accepted like value: []. The refusal for any other value beside clear: true now reads "clear: true writes the field's empty value, so pass it without a value" instead of "clear: true writes an empty list, so pass it without a value".

Removes nothing: no existing capability is removed or renamed.

Tests

Unit (TestDashboardWriteClear, 28 cases):

  • test_clear_posts_an_empty_list_for_an_array_field -- array field gets []
  • test_clear_posts_an_empty_object_for_an_object_field -- object field gets {}
  • test_clear_beside_an_empty_object_is_the_same_write -- value: {} beside clear is treated as a clear
  • test_clear_on_a_scalar_field_falls_through_to_the_gateway -- string field gets [], and the write route's wrong_type refusal comes back whole
  • test_clear_on_an_unknown_field_posts_an_empty_list_for_the_route_to_refuse -- unknown field gets [], so the write route gives its own refusal
  • test_clear_posts_an_empty_list_when_the_field_list_cannot_be_read -- the fields GET returns an error, a refused connection, no fields key, or a fields value that is not a list; the write still posts [] (4 cases)

End-to-end (test_clear_through_the_panel_server_empties_an_object_field): drives the full path from mcp_panel._call_tool over loopback HTTP to the real route, reads back, asserts value is {} with no wrong_type mistake entry.

Existing test_clear_through_the_panel_server_empties_an_array_field still passes.

Manual verification

N/A -- unit and end-to-end coverage sufficient. This is a pure backend change with no user-visible UI surface.

Screenshots / video

N/A -- backend tool change only, no frontend surface modified.

Related Issues

Closes #20089

Pattern harvest

Rule candidate: agents-md
Pattern: a clear flag that maps to a single hardcoded empty value ([]) fails for fields whose type is not that value; read the field's declared type at the call site and dispatch to the matching empty value.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@chenmingwei23
chenmingwei23 requested review from a team and KiroCrewCaptain as code owners October 14, 2026 09:39
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 14, 2026
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 221ad46690863722be3fc92d000bed285102579e touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 221ad46690863722be3fc92d000bed285102579e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that the type each /api/agent-panel/dashboard/fields row reports comes from the same declaration the write route type-checks against.

Suggestions

  • If a later PR is allowed to change the write route, have it accept clear and pick the empty value from its own field declaration. That would drop the extra GET before each clear and keep the field-type lookup in one place instead of two.

[DESIGN-REVIEWED] 221ad46

Description read

[DESCRIPTION-READ] f9cc8e426a202962c4668de34452bb4da66714a4b3b1a08e66d5c50e439e2ff9

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 221ad46690863722be3fc92d000bed285102579e — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Nothing to check.

What this change ships

Inventory (6 items) — 6 justified

Intent: an agent can empty an object field on the dashboard (such as goal-board asks) through dashboard_write, where today every attempt is refused and logged as a mistake. FIX.

  1. clear: true on an object field now writes {} and succeeds, where before it was refused as wrong_type — justified
  2. Each clear first reads the field list once to find the field's type, and writes [] when that list can't be read — justified
  3. A clear on a string, number, boolean, fold-sourced or unknown field still goes to the gateway, which refuses it and records it in the mistake book — justified
  4. value: {} sent alongside clear: true is now accepted, as value: [] already was — justified
  5. The refusal for any other value sent with clear now reads "writes the field's empty value" instead of "writes an empty list" — justified
  6. The tool description, the clear parameter text, the no-value error and the spec now say "array or object field" — justified

[FIRST-PRINCIPLES-REVIEWED] 221ad46

Description read

[DESCRIPTION-READ] 9b73b10bec9d61f7de451fbb6076d4e10ba3dade4d228a2656458d0adc55322c

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 221ad46690863722be3fc92d000bed285102579e — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 221ad46

Verdict parsed from the review's SHA-scoped output markers for commit 221ad46690863722be3fc92d000bed285102579e.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 221ad46690863722be3fc92d000bed285102579e: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 221ad46690863722be3fc92d000bed285102579e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 221ad46

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 221ad46690863722be3fc92d000bed285102579e: <one-sentence reason>

@chenmingwei23
chenmingwei23 enabled auto-merge (squash) October 14, 2026 10:29
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 14, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Request changes at 56a74f7.

The core fix is sound: clear: true on an object field now writes {} and the end-to-end test covers it. Two things need fixing before approval, and none of the Design, First Principles or Opus items have a reply yet.

  1. The owning spec contradicts the code. dashboard-instances.md#L24 says string/number/boolean fields "are refused before the POST", but _empty_value_for returns [] for them and lets the gateway refuse with wrong_type / field_not_agentic. The description's Not a goal and Tests sections say the same old thing (test_clear_on_a_string_field_is_refused_before_the_gateway no longer exists). Smallest fix: change the spec sentence and the description to say non-object clears go to the write route, which refuses them; optionally drop the redundant if row is None branch.
  2. Array clears gained a new failure mode. mcp_panel.py#L1027 returns an error when the fields GET fails, so a clear that only needed the write route before now fails, while the description says no working call stops working. Smallest fix: on a GET failure fall back to [] (the old behaviour) and let the gateway type-check, or name the new dependency in Backwards compatibility.

Please post a disposition for each Design / First Principles item after the change. Checks on this head are green.

— crew-pr-reviewer (r100)

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 14, 2026
When clear: true is passed to dashboard_write, the panel server now
reads the field's declared type from the dashboard/fields route and
writes the matching empty value: [] for array fields and {} for object
fields. Previously only [] was written, which the gateway refused as
wrong_type for object fields (asks, drafts, steps). Calls that pass a
value are unchanged.

Closes #20089 (part 2; part 1 is #20144)
_empty_value_for returns {} for an object field and [] for every other
field, including string, number, boolean and fold-sourced fields,
instead of refusing early. The write route then refuses those with
wrong_type or field_not_agentic and records the refusal in the mistake
book; an early refusal duplicated the gateway's check and bypassed the
book.

A field list that cannot be read also gets [], the value clear: true
wrote before object fields were supported, so emptying an array field
does not depend on the fields route answering. The owning spec now
says the same instead of claiming scalar clears are refused before the
POST.
@chenmingwei23
chenmingwei23 force-pushed the fix/dashboard-write-object-clear-20089 branch from 56a74f7 to 221ad46 Compare October 14, 2026 22:29
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 14, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • Spec and description describe the old design span=92c50665b655

fixed in 221ad46

fixed: the spec paragraph in dashboard-instances.md now says the MCP server posts {} for an object field and [] for any other field, and that string, number, boolean, fold-sourced and unknown fields reach the write route, which refuses them (wrong_type, field_not_agentic, unknown_field) and records the refusal in the mistake book.
The description's What changed and Tests sections say the same. The deleted test name is gone and test_clear_on_a_scalar_field_falls_through_to_the_gateway is listed instead.
Not a goal is frozen once a PR opens (AGENTS.md, "PR goal is frozen"), so its outdated parenthetical stays as written; What changed now carries an explicit correction of it.
Both commit messages are reworded, so the squash message no longer says scalar clears are refused before the POST.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • Clearing an array field now needs a working field list span=318f36c15c11

fixed in 221ad46

fixed: _empty_value_for in mcp_panel.py returns no error when the fields GET fails. A failed GET, a reply with no fields key, or a fields value that is not a list all give [], the value clear: true wrote before this PR, and the write route type-checks it.
Clearing an array field therefore needs only the write route, as it did before this PR.
Test: test_clear_posts_an_empty_list_when_the_field_list_cannot_be_read (4 cases: route error, refused connection, no fields key, fields not a list) asserts the POST carries [].
Backwards compatibility now names the fallback and the one extra GET each clear makes.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • Spec says scalar clears are refused before the POST (item 5) span=ca59951248da

fixed in 221ad46

fixed: the sentence "Fields of other types (string, number, boolean) are refused before the POST" is deleted from dashboard-instances.md. The paragraph now says those fields reach the write route, which refuses them and records the refusal in the mistake book.
The second subtraction is taken too: the redundant if row is None branch is gone, and so is the (value, refusal) tuple, since no refusal path is left. _empty_value_for is one loop that returns {} for an object field and [] for anything else.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • Inventory item 2: a failed fields GET made array clears fail

fixed in 221ad46

fixed: a failed fields GET, or a reply with no usable field list, now gives [], the value clear: true wrote before this PR, so an array clear works whenever the write route does.
The "no call that works today stops working" claim in Backwards compatibility holds again, and that section now names the one extra GET each clear makes.
Covered by test_clear_posts_an_empty_list_when_the_field_list_cannot_be_read (4 cases).

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • Inventory item 3: value: {} beside clear: true is accepted like value: []

rebutted

kept: clear: true means "write this field's empty value", and the tool-schema check accepts a value beside it only when that value says the same thing.
Before this PR the check accepted [] beside the flag. Now that object fields can be cleared, {} beside the flag is the same coherent call; refusing it would answer "pass it without a value" although nothing contradicts the flag.
The server still writes the empty value of the field's declared type, so the extra value never decides what is written.
Covered by test_clear_beside_an_empty_object_is_the_same_write.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • dashboard-instances.md:24 says scalar clears are refused before the POST span=e4c8103ce311

fixed in 221ad46

fixed: the sentence is replaced. The spec now says the MCP server does not refuse a clear for the field's type or source; string, number, boolean, fold-sourced and unknown fields reach the write route, which refuses them (wrong_type, field_not_agentic, unknown_field) and records the refusal in the mistake book.
This matches _empty_value_for, which returns {} for an object field and [] for every other field, and test_clear_on_a_scalar_field_falls_through_to_the_gateway.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Thanks for the review. Both items are addressed in 221ad46. The PR is still 2 commits, and both commit messages are reworded so the squash message matches the code.

  1. Spec vs code. dashboard-instances.md now says non-object clears go to the write route, which refuses them (wrong_type, field_not_agentic, unknown_field) and records the refusal in the mistake book. The description's What changed and Tests sections say the same, and the deleted test name is gone. Not a goal is frozen once a PR opens (AGENTS.md, "PR goal is frozen"), so its outdated parenthetical stays as written; What changed now carries an explicit correction of it. The redundant if row is None branch is gone as well: _empty_value_for is one loop that returns {} for an object field and [] for anything else.

  2. Array clears and the fields GET. A failed fields GET now falls back to [], the value clear: true wrote before this PR, and the write route type-checks it. New test: test_clear_posts_an_empty_list_when_the_field_list_cannot_be_read (route error, refused connection, no fields key, fields not a list). Backwards compatibility names the fallback and the one extra GET each clear makes.

Each Design, First Principles and Opus item has its own disposition comment on this PR. Could you take another look?

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • Punchline: the fields row's type and the write route's type check come from one declaration

rebutted

checked, it holds: the fields route builds each row from read_instance in agent_panel.py, which reads dashboard_templates.instance.read, and fields_for_agent copies spec.type from that manifest.
The write route's read_package_model falls through to _from_template_instance in dashboard_package.py when no package is bound; that reads the same instance store with read_instance's rule verbatim, and check_write type-checks against spec.type of that manifest.
When a package is bound, or is present and broken, the write route refuses every value before the type check, so a clear cannot land on a field whose type the two routes disagree about.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • Suggestion: let the write route accept clear and pick the empty value itself span=65a795103fff

rebutted

not in this PR: Not a goal excludes changing the gateway write route and DASHBOARD_WRITE_SCHEMA, so the clear stays in the MCP server and the route sees an ordinary write.
The cost of that split is one extra GET per clear, declared in Backwards compatibility, and a failed GET falls back to [], so an array clear needs only the write route.
The suggestion fits a later PR that is allowed to change the route; nothing in this one stands in its way.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 14, 2026

@mbriones98 mbriones98 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checks green and readiness passed at 221ad46; no behavior change.

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE at 221ad46.

Both items from my r100 change request are fixed. The spec now says string, number, boolean, fold-sourced and unknown fields reach the write route, which refuses them and records the refusal (dashboard-instances.md). A failed fields read falls back to [], so array clears no longer depend on the fields route (mcp_panel.py L1014-L1036). The fields route it reads is side-effect free, and _get returns an error dict rather than raising.

All current-head AI lanes are PASS or no findings. The Design punchline and its optional suggestion both have evidence-backed replies. The tests cover object, array, scalar and unknown fields, the four unreadable-list cases, and an end-to-end clear of asks to {}. CI on this head is green. I read the code and tests; I did not run them.

— crew-pr-reviewer (r102)

@iamwhatever
iamwhatever merged commit e98df2e into main Oct 15, 2026
103 checks passed
@iamwhatever
iamwhatever deleted the fix/dashboard-write-object-clear-20089 branch October 15, 2026 01:32
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MCP tools whose documented clear is an empty list or object cannot clear through Kiro CLI

3 participants