Skip to content

Add plugin cli-agent-bridge - #7

Open
Hylouis233 wants to merge 40 commits into
MiniMax-AI:mainfrom
Hylouis233:plugin/cli-agent-bridge
Open

Add plugin cli-agent-bridge#7
Hylouis233 wants to merge 40 commits into
MiniMax-AI:mainfrom
Hylouis233:plugin/cli-agent-bridge

Conversation

@Hylouis233

@Hylouis233 Hylouis233 commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

Migrated from hetaoBackend/MiniMax-Code-Plugins#16 (full review history and prior rounds of feedback live there). Head commit: 8f87ae4.


What changes

Adds the hosted Plugin plugins/Hylouis233/cli-agent-bridge: a dependency-free stdio MCP server
and same-name Skill that let MiniMax Code delegate bounded coding tasks to locally installed
Claude Code, Codex CLI, Kimi Code, ZCode, or DSH processes inside a Git repository, then review
the resulting workspace and commit changes.

The server exposes three tools:

  • list_backends reports configured CLIs, availability, versions, and experimental notes.
  • workspace_status returns a bounded Git snapshot: status, staged/unstaged diff stats, changed
    files (including untracked paths), HEAD and symbolic HEAD, and refs.
  • delegate_task runs one backend and returns the exit code, bounded stdout/stderr tails,
    before/after Git snapshots, moved refs, and an attributed commits block. Dirty worktrees are
    rejected unless allowDirty=true; unsupported resume requests fail instead of silently starting
    a fresh session.

Safety and concurrency behavior

  • Calls targeting the same Git common directory are serialized across subdirectory aliases,
    symlinks, linked worktrees, independent MCP clients, and bridge processes. Independent clones
    can still run in parallel.
  • Coordination state lives in a private bare lock store under the Git common directory; bridge
    refs never enter the target repository and therefore do not leak through git push --mirror.
    The lock store inherits core.sharedRepository and uses compare-and-swap owner records,
    cross-process failed-release recovery, read-only ownership probes, and safe automatic Git
    maintenance.
  • Cancellation and the overall deadline cover discovery, lock waits, snapshots, the backend, and
    post-run attribution. Backend process trees, plus descendants spawned by Git hooks/helpers, are
    contained and confirmed terminated before the repository lease is released. Uncertain worker
    termination fails closed behind a shared quarantine marker.
  • Git attribution handles unborn HEADs, same-commit symbolic-HEAD changes, force-moved and
    non-commit refs, fetched remote/tag/prefetch history, more than 256 baseline tips, linked
    worktrees, submodules, unusual path bytes, and staged/untracked changes without presenting a
    truncated snapshot as complete.
  • The server makes no network calls and stores no credentials or session logs. The selected backend
    CLI uses the user's own authentication and may send task/workspace data to its provider. Private
    coordination records contain process/lease metadata; a quarantine marker persists only when
    manual recovery is required.

User value

MiniMax Code remains the orchestrator while specialized coding CLIs perform self-contained work.
Every result includes reviewable Git evidence instead of relying on copied terminal output.

Example prompt:

Use the cli-agent-bridge skill, then delegate the login-form refactor in this repository to codex.

For independent comparison runs, create separate clean clones at the same starting commit; linked
worktrees intentionally share the repository lock and queue instead of running concurrently.

Requirements and disclosure

  • Node.js 20 or newer and Git on PATH; no npm runtime dependencies.
  • Windows, Linux, and macOS are supported. Windows shim commands use the bundled PowerShell 5.1
    runner. The implementation is exercised on Windows and Linux; the macOS POSIX path is supported
    but has not been machine-verified in this PR.
  • Backend CLIs must already be installed, authenticated, and configured by the user. Claude,
    Codex, and Kimi templates are non-experimental; ZCode and DSH remain explicitly experimental.
  • No credentials, installers, native binaries, private endpoints, or telemetry are bundled.

Verification

Verified on current head 6f158b2:

  • Linux container npm run check: 107 tests, 104 passed, 3 platform-specific skips, 0 failed.
  • Original plugin integration suite (test/server.test.mjs): 11/11 passed, including protocol
    negotiation, tool discovery, untracked files, dirty-tree refusal, unknown backends,
    cancellation, before/after snapshots, same-workspace serialization, queued cancellation,
    unborn HEAD, and Codex option delimiters.
  • Targeted Linux fixture proves an escaped fsmonitor-hook descendant is terminated before return.
  • Targeted recovery fixture proves a failed release is recoverable through a separately loaded
    module instance with no shared in-memory recovery state; ownership probes do not manufacture
    heartbeat blobs.
  • git diff --check is clean.
  • GitHub validate, analyze, and CodeQL checks all pass.

Submission checklist

  • Plugin path, manifest name, license, examples, requirements, platforms, accounts, network/data
    behavior, and experimental backends are disclosed.
  • No scaffold TODOs, credentials, symlinks, installers, or native binaries are included.
  • Repository validation and test suites pass on the current head.

View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.

Hylouis233 and others added 30 commits August 15, 2026 17:03
Delegate coding tasks from MiniMax Code to locally installed coding CLIs (Claude Code, Codex, Kimi Code, ZCode, DSH) through a dependency-free stdio MCP server with git-diff review. See NOTICE for upstream credits.
- claude template gains --permission-mode acceptEdits so headless runs can
  actually edit files (verified end-to-end with Claude Code 2.1.226)
- kimi keeps plain -p prompt mode: --auto/-y are mutually exclusive with -p
  on current Kimi Code versions
- git snapshot now lists untracked files (git ls-files --others) so new files
  created by workers appear in changed files
- README/SKILL document permission defaults and honest backend verification
  status
npm-style .ps1/.cmd shims cannot be spawned directly on Windows, so runCommand retries them through the bundled ps1-runner.ps1 (Windows PowerShell 5.1) with verbatim argument forwarding. README documents the fallback and the custom-wrapper caveat.
- per-workspace serialization of delegate_task
- SIGTERM then SIGKILL force kill after timeout grace
- snapshots include staged, untracked files and committed deltas
- delegate_task marked destructiveHint, isError on failures
- notifications/cancelled kills the worker
- honest protocol version negotiation
- fail closed when git snapshot commands fail
- ring-buffer output capture without repeated large copies
- README discloses supported operating systems
SKILL workflow and README tool description now cover before/after snapshots, committed deltas, same-workspace serialization, isError semantics, force-kill timeouts, and cancellation.
Seven self-contained tests cover protocol negotiation, tool list, snapshots, dirty-tree guard, unknown backends, cancellation, and before/after snapshots. SKILL wording now notes same-workspace serialization.
- workspace lock is now keyed by the canonical realpath of the git worktree
  root (git rev-parse --show-toplevel + fs.realpath), so the same checkout
  reached via a subdirectory, casing, or symlink shares one mutex (P1)
- a delegation cancelled while queued for the lock re-checks the cancel flag
  after acquiring it and returns before spawning the worker (P1)
- timeout and cancellation now terminate the whole process tree: taskkill
  /PID /T /F on Windows, signal to the detached process group on POSIX,
  instead of only killing the top-level child (P1)
- git snapshots tolerate an unborn HEAD (fresh git init) and committedDelta
  reports the first commits when the worker started from no commits (P2)
- codex templates delimit the prompt with -- so option-like tasks are not
  parsed as CLI flags (P2)
- README comparison example now requires two independent git worktrees; the
  queued same-checkout second run is documented as follow-up work (P2)
- SKILL resume guidance no longer implies results carry backend session ids

Tests extended to 11 (protocol, tools, snapshots, dirty guard, unknown
backend, in-flight cancel, before/after, worktree-root lock serialization,
cancel-while-queued, unborn HEAD, codex -- delimiter); 3 consecutive runs
green locally
- gitSnapshot/committedDelta executed their git commands via Promise.all;
  git status and git diff both refresh the index, so concurrent processes
  raced for .git/index.lock and intermittently failed with exit code 128,
  surfacing as random 'git snapshot unreliable' errors (reproduced 1-in-15
  on Windows; the fail-closed guard turned it into a JSON-RPC error)
- commands now run serially per repository; 10/10 Windows runs and a full
  npm run check in a Linux node:22 container pass
- test harness: every server now stops in a finally block (a leaked server
  kept stdin/stdout pipes open and hung node --test when an assertion
  failed - the cause of the stalled CI validate job), in-flight cancel test
  bounds its worker with an explicit timeoutMs
…ribution

- disclose repository concurrency: linked worktrees share refs, so snapshots
  detect other active leases plus completed runs' history records and mark
  attribution as potentially overlapping (repositoryConcurrency)
- attribute only genuinely new commits: ranges exclude all pre-delegation
  refs, so a branch checkout is reported as a HEAD move with no new commits,
  and non-commit refs (blob tags) are reported without failing the run
- verify process identity before signaling: Windows tracks creation times,
  POSIX groups are signaled only while the original leader identity matches,
  and reused PIDs are dropped from the tracked tree
- make lease state updates interruptible by the request cancellation/deadline
  and resync the interrupted release by owner token
- move quarantined leases to a recoverable state: removing the quarantine
  marker authorizes the next delegation to reclaim
- catch process-tree inspection failures in the close handler (fail closed
  instead of an unhandled rejection) and slow the Linux /proc monitor to 250ms
- tests: 55 total (checkout attribution, blob refs, concurrency disclosure,
  lease interruption, quarantined reclaim, PID-reuse identity)
- deduplicate HEAD and branch-ref targets so a commit on the checked-out
  branch is logged, diffed, and counted once with both labels
- diff new refs from their merge-base with the pre-delegation state, so a
  branch forked from a divergent branch never attributes pre-existing
  differences to the worker
- register list_backends in activeRequests and terminate a hanging version
  probe on cancellation, skipping the remaining probes
- signal the process group when enumeration is unavailable (containment wins
  when identity cannot be verified)
- strip only Git's line terminator from rev-parse --show-toplevel so a
  worktree root ending in whitespace canonicalizes correctly
- tests: 60 total, all green locally
Add cross-process repository locking, fail-closed process containment, safe Git attribution, explicit quarantine recovery, Windows Job Object execution, and regression coverage for reviewed lifecycle and documentable safety boundaries.
Copilot AI lite review requested due to automatic review settings August 19, 2026 09:16

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

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.

2 participants