Simplify show changes tool schema

[Waishnav]

Summary

• remove model-facing since and markReviewed inputs from show_changes
• keep checkpoint behavior inside DevSpace by always comparing against last_shown and marking the diff reviewed
• document the minimal end-of-turn show-changes workflow

Testing

• npm run typecheck
• npm test

Summary by CodeRabbit

• Documentation

  • Clarified guidance for when change summaries should be shown after file edits.
  • Updated the usage contract to reflect that only the workspace identifier is needed.

• Bug Fixes

  • Streamlined change-summary behavior so it consistently uses the latest checkpoint and marks changes as reviewed automatically.
  • Improved consistency in how file changes are reported after edits.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4c4ada03-fc92-4af3-be1b-584b4b83ac7a

📥 Commits

Reviewing files that changed from the base of the PR and between 9e16b35 and 14786d9.

📒 Files selected for processing (2)

• docs/chatgpt-coding-workflow.md
• src/server.ts

✅ Files skipped from review due to trivial changes (1)

• docs/chatgpt-coding-workflow.md

🚧 Files skipped from review as they are similar to previous changes (1)

• src/server.ts

---

📝 Walkthrough

Walkthrough

Simplifies the show_changes MCP tool contract by removing the since and markReviewed input parameters, fixing the handler to always use since: "last_shown" and markReviewed: true. Updates serverInstructions wording and adds usage documentation in docs/chatgpt-coding-workflow.md.

Changes

show_changes contract simplification

Layer / File(s)	Summary
show_changes tool contract and docs src/server.ts, docs/chatgpt-coding-workflow.md	Removes since/markReviewed from the inputSchema, hardcodes the handler to use since: "last_shown" and markReviewed: true, updates instruction wording to reference "individual file change(s)", and documents the exactly-once-per-turn invocation contract.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Model
  participant MCPServer
  participant ReviewCheckpoints
  Model->>MCPServer: call show_changes(workspaceId)
  MCPServer->>ReviewCheckpoints: reviewChanges(since: "last_shown", markReviewed: true)
  ReviewCheckpoints-->>MCPServer: aggregate diff since last checkpoint
  MCPServer-->>Model: rendered diff, checkpoint advanced

Loading

Possibly related PRs

• Waishnav/devspace#48: Also modifies serverInstructions and the show_changes tool contract/timing behavior in src/server.ts.

Poem

A hop, a diff, a checkpoint's cheer,
One call to show what's changed round here.
No more "since" to fuss and choose,
Just "last_shown" — no time to lose!
🐇✨ Thumping tail, the diff is clear.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: simplifying the show_changes tool schema and contract.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch simplify-show-changes-schema

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR simplifies the model-facing show_changes tool interface by removing optional inputs and standardizing checkpoint behavior inside DevSpace, and it adds documentation plus example “agent profile” templates to illustrate the emerging profile format.

Changes:

• Remove model-facing since / markReviewed inputs from the show_changes MCP tool and always compare against last_shown while marking reviewed.
• Document the minimal end-of-turn show_changes workflow.
• Add and ship example local-agent profile templates (examples/agents) plus a draft schema document.

Reviewed changes

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

Show a summary per file

File	Description
src/server.ts	Simplifies show_changes tool schema and hard-codes checkpoint behavior to last_shown + mark reviewed.
package.json	Publishes the new examples/ directory in the npm package.
examples/agents/README.md	Adds guidance for the agent-profile examples directory.
examples/agents/pi-reviewer.md	Adds a read-only “pi” reviewer profile template.
examples/agents/opencode-explorer.md	Adds a read-only “opencode” explorer profile template.
examples/agents/cursor-agent-worker.md	Adds a writable “cursor” worker profile template.
examples/agents/copilot-reviewer.md	Adds a read-only “copilot” reviewer profile template.
examples/agents/codex-worker.md	Adds a writable “codex” worker profile template.
examples/agents/codex-explorer.md	Adds a read-only “codex” explorer profile template.
examples/agents/claude-implementer.md	Adds a writable “claude” implementer profile template.
docs/chatgpt-coding-workflow.md	Documents the simplified show_changes end-of-turn calling convention and checkpoint behavior.
docs/agent-profile-schema.md	Introduces a draft “agent profile” schema and conventions for the example templates.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/agents/README.md`:
- Line 14: The README’s schema link points to a non-repo-relative path, so
update the reference in the agents README to use a repo-relative link from
`examples/agents/README.md` to the draft schema. Make sure the link resolves
correctly when viewed from that directory, and if this README is included in the
npm tarball, verify the target doc is published there or point the link at a
shipped location instead.

In `@src/server.ts`:
- Around line 1165-1176: The show_changes tool is incorrectly marked as
read-only even though the reviewChanges call uses markReviewed: true and mutates
the review baseline. In the tool descriptor in src/server.ts where
toolWidgetDescriptorMeta(config, "show_changes") is defined, remove the
annotations.readOnlyHint flag so the tool is treated as state-changing and won’t
be auto-run by clients.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2fdff6a0-20d1-43b3-a89b-eb6e406f3500

📥 Commits

Reviewing files that changed from the base of the PR and between 323d862 and 9e16b35.

📒 Files selected for processing (12)

• docs/agent-profile-schema.md
• docs/chatgpt-coding-workflow.md
• examples/agents/README.md
• examples/agents/claude-implementer.md
• examples/agents/codex-explorer.md
• examples/agents/codex-worker.md
• examples/agents/copilot-reviewer.md
• examples/agents/cursor-agent-worker.md
• examples/agents/opencode-explorer.md
• examples/agents/pi-reviewer.md
• package.json
• src/server.ts