feat(agent): miner write-tools — local-execution action specs (#780)

[JSONbored]

Closes #780

What & why

Phase 2 (#770). New MCP write-tools the miner's own local harness runs with its own GitHub creds. Per the agreed contract: gittensory supplies the content, and the tool's output is an action spec — gittensory and this MCP package never perform the write, so source code and the write both stay on the miner's machine.

Tools

gittensory_open_pr, gittensory_file_issue, gittensory_apply_labels, gittensory_post_eligibility_comment, gittensory_create_branch, gittensory_delete_branch.

Each returns a LocalWriteActionSpec:

• command — a POSIX single-quote-escaped, directly-runnable gh/git command (safe to exec verbatim — injection-safe against titles/bodies with quotes),
• inputs — the structured params, so the harness can reconstruct its own invocation instead,
• boundary — the local-execution contract note.

How

• src/mcp/local-write-tools.ts — pure, deterministic builders (no GitHub calls, no state). open_pr pairs with prepare_pr_packet for content.
• src/mcp/server.ts — register the six tools (each labelled local-only) + a thin localWriteSpec wrapper.

Boundary

gittensory never touches git/GitHub here — it returns a spec the harness executes locally. The no-cloud-write boundary is preserved end to end.

Tests

Every builder (command shape, single-quote escaping, optional draft/labels/base/remote) + the MCP round-trip for all six tools. New code 100% covered; MCP discovery/output-schema meta-tests green; full suite green (2106 passed).

[ghost]

Note

Gittensory Gate skipped

PR closed before full evaluation. No late first comment was created.

Signal	Result	Evidence	Action
Gate result	⚠️ Skipped	#848 is no longer open.	No action.

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.67%. Comparing base (2e06410) to head (68eeed0).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #848   +/-   ##
=======================================
  Coverage   96.66%   96.67%           
=======================================
  Files         106      107    +1     
  Lines       14495    14538   +43     
  Branches     5269     5274    +5     
=======================================
+ Hits        14012    14055   +43     
  Misses        105      105           
  Partials      378      378           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ghost]

gittensory · advisory review

Reviewed 4 changed file(s) — two independent AI reviewers.

Changed files: src/mcp/local-write-tools.ts, src/mcp/server.ts, test/unit/local-write-tools.test.ts, test/unit/mcp-write-tools.test.ts

Suggested action: ✅ Safe to merge — both reviewers found no blocking issues.

Reviewer A · gpt-oss-120b — recommends ✅ merge
The PR introduces a new suite of local write‑tool specs, registers corresponding MCP tools, and adds comprehensive unit tests. The implementation safely escapes inputs, respects the no‑cloud‑write boundary, and integrates cleanly with existing server logic.

Suggestions

• Wrap localWriteActionOutputSchema in z.object({...}) for consistency with other schemas.
• Consider adding a test case for quoting edge‑cases beyond single quotes (e.g., backticks or spaces) to confirm the shell‑escaping remains safe.

Worth double-checking

• Ensure the server’s tool registration expects plain objects for output schemas; otherwise the new tools may fail validation at runtime.

Reviewer B · nemotron-3-120b-a12b — recommends ✅ merge
The PR adds miner write-tools for local execution, allowing the MCP server to generate shell-safe action specs (e.g., for opening PRs, filing issues) that miners run with their own credentials. The changes are focused, well-tested, and respect the public/private boundary by ensuring Gittensory never performs writes. Input validation and shell escaping appear correct.

Suggestions

• Consider shortening the summary in localWriteSpec to avoid overly long MCP tool summaries (currently includes the full boundary string).
• Add a test case for sq escaping edge cases (e.g., multiple consecutive single quotes, backslashes) to ensure robustness across shells.

Worth double-checking

• Shell escaping assumes POSIX-compliant shells (e.g., bash, zsh); non-POSIX shells (e.g., fish) may require different escaping.
• The inputs record uses z.unknown(); while acceptable for output schema, ensure consumers handle mixed types correctly.