feat(agent): MCP automation-state read tool (advances #784)

[JSONbored]

Advances #784 (does not close it).

What & why

Phase 3 (#784) — MCP control-surface slice (read side). New MCP tool gittensory_get_automation_state(owner, repo) surfaces a repo's agent automation posture so a maintainer's harness can read it:

• per-action autonomy levels,
• kill-switch / dry-run mode (resolved: paused / dry_run / live),
• GitHub write-permission readiness (ready / reconsent_required / not_required),
• the acting action classes,
• the count of auto_with_approval actions awaiting a maintainer decision.

Repo-access scoped (consistent with gittensory_get_repo_context).

Scope boundary (so it doesn't step on contributor work)

• Read-only + count-only. The full approval queue and accept/reject stay behind the maintainer-authed REST API (feat(agent): approval-queue UX + notification channel #779) and the dashboard/CLI surfaces — the MCP tool never leaks the queue's action details.
• Does not close feat(agent): automation controls surface (dashboard + CLI + MCP) #784. The dashboard slice (audit feed) is in flight via the contributor PR feat(ui): audit feed / skipped-PR viewer #831; the CLI maintain slice and the MCP accept/reject write path remain. This is one clean increment toward feat(agent): automation controls surface (dashboard + CLI + MCP) #784's "MCP: read autonomy state" deliverable.

Tests

A configured repo (autonomy + dry-run mode + write-ready + pending count) and an unknown/un-onboarded repo (unconfigured, not_required, no installation). New code 100% covered; MCP discovery/output-schema meta-tests green; full suite green (2120 passed).

[ghost]

Note

Gittensory Gate skipped

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

Signal	Result	Evidence	Action
Gate result	⚠️ Skipped	#851 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.68%. Comparing base (134b0c3) to head (54372cb).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #851   +/-   ##
=======================================
  Coverage   96.68%   96.68%           
=======================================
  Files         108      108           
  Lines       14609    14621   +12     
  Branches     5288     5290    +2     
=======================================
+ Hits        14125    14137   +12     
  Misses        105      105           
  Partials      379      379           

☔ 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 2 changed file(s) — two independent AI reviewers.

Changed files: src/mcp/server.ts, test/unit/mcp-automation-state.test.ts

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

Reviewer A · gpt-oss-120b — recommends ✅ merge
This PR adds a new MCP tool gittensory_get_automation_state that returns a repository's agent automation state, along with a comprehensive unit test suite exercising configured and unconfigured repo scenarios. The implementation integrates existing settings and DB helpers without breaking existing functionality.

Suggestions

• Add a test case covering the global agent pause path to ensure mode reflects the paused state correctly.
• Guard against a possible null settings return from getRepositorySettings (e.g., provide a default object) to avoid runtime errors on unknown repos.
• Document the new tool in the MCP API reference so downstream users know its input and output schema.

Worth double-checking

• If getRepositorySettings can return null, the current code may throw when accessing its properties.
• The output schema must stay in sync with the actual returned data; a mismatch could cause client validation failures.

Reviewer B · nemotron-3-120b-a12b — recommends ✅ merge
The PR adds a new MCP tool 'gittensory_get_automation_state' to read a repository's agent automation state (autonomy settings, mode, permission readiness, and pending approval count). It includes proper repo-access scoping, uses existing internal services, and avoids leaking forbidden public terms. The accompanying unit test covers basic configured/unconfigured scenarios and checks for absence of forbidden terms. The change is focused, well-tested, and maintains the public/private boundary.

Suggestions

• Consider adding a test case for edge scenarios like global agent pause or missing installation permissions to further validate mode and permissionReadiness outputs.
• Ensure the output schema's optional fields align with actual return values (e.g., 'autoMaintain' may be undefined if not configured).

Worth double-checking

• Verify that 'listPendingAgentActions' correctly filters by status='pending' and repoFullName to avoid cross-repo data leakage.
• Confirm that 'resolveAgentPermissionReadiness' handles null installation permissions safely (as in the test's 'not_required' case).