Add goudan-side acp-inbox-bridge skill (v0.3.0)

[antianqi]

Add goudan-side acp-inbox-bridge skill (v0.3.0)

What

This PR adds the goudan (OpenClaw main agent) perspective to the
bridge that the mavis side already drives. The v0.2.0 release exposed
acp-collab (mavis / MiniMax Code) and acp-task-dispatch (mavis
dispatch); the goudan-side companion was deliberately deferred to a
follow-up so the review surface for each PR stays small.

This PR is built on top of PR #3 (add-openclaw-acp-bridge,
head 07c6358), which hetaoBackend approved on 2026-09-01 but has
not yet been merged. The diff below includes PR #3's content; the
reviewer should focus on the 5 new files (the goudan-side additions)
plus the metadata changes in plugin.json / README.md. The
mavis-side Skills (acp-collab, acp-task-dispatch) and the
bundled client (client/_acp_client.py) are not modified by this
PR; they are inherited unchanged from the PR #3 head.

The new content is:

File	Status	Bytes	Purpose
skills/acp-inbox-bridge/SKILL.md	new	8.6 KB	goudan-side Skill (default sender="goudan")
scripts/acp_inbox.py	new	9.5 KB	thin class-style wrapper (ACPInbox) over client/_acp_client.inbox_*
scripts/test_inbox_goudan.py	new	24 KB	24-check smoke (static + live + CLI)
plugin.json	modified	+1 -1	version 0.2.0 -> 0.3.0, description mentions goudan-side
README.md	modified	+30 -3	new "Goudan-side companion" section

Why

PR #3 reviewer noted in the round-5 approval that the goudan-side was
out of scope and should come as a follow-up. This PR is that
follow-up. Keeping the PR small makes review tractable: this commit
touches only NEW files plus the two pieces of metadata (plugin.json,
README.md) that have to reflect the new skill. None of the files
that the round-1 through round-5 reviews in PR #3 touched are
modified by this commit; it cannot regress them.

How to read the diff

On GitHub, the file-level diff includes both PR #3 changes (already
approved) and the goudan-side additions (this PR). The reviewer
should:

1. For the loopback / no-redirect / token-boundary contract:
   look at PR Add antianqi/openclaw-acp-bridge v0.1.3 - peer collaboration Bridge for MiniMax Code #3 head 07c6358; this PR inherits that contract
   unchanged.
2. For the new content: focus on
   • skills/acp-inbox-bridge/SKILL.md
   • scripts/acp_inbox.py
   • scripts/test_inbox_goudan.py
   • the diffs to plugin.json and README.md

Validation

• python scripts/test_inbox_goudan.py (live, stub-backed):
  36/36 PASS, 0 FAIL, 0 SKIP on Windows + Python 3.14.
  Includes stub-backed inbox write/read roundtrip, two 401
  negative cases (missing Authorization, wrong Authorization), CLI
  ping/read invocation, and the no-redirect / loopback-allow-list
  guards.
• python scripts/test_inbox_goudan.py (CI mode,
  SMOKE_SKIP_LIVE=1): 21/21 PASS, 0 FAIL, 10 SKIP. The 10
  skipped checks are the live-server ones; the static checks
  (sender defaults, no-redirect opener, loopback guard, token
  resolution, no hardcoded paths, ACP_PLUGIN_ROOT / file
  resolution, mock-based delegation) all pass without a live
  server.
• python scripts/smoke.py (PR Add antianqi/openclaw-acp-bridge v0.1.3 - peer collaboration Bridge for MiniMax Code #3's mavis-side smoke, regression
  check): 26/26 PASS, 0 FAIL. Zero regression on the mavis
  side. The new SKILL.md is automatically picked up by
  Check 7 ("Plugin SKILL.md files resolve the plugin root
  safely") and passes.
• python scripts/test_no_redirect.py (PR Add antianqi/openclaw-acp-bridge v0.1.3 - peer collaboration Bridge for MiniMax Code #3's no-redirect
  regression): 1/1 PASS. The no-redirect guarantee still
  holds for the underlying client/_acp_client; the wrapper
  inherits it.
• node scripts/validate.mjs (repo validator): no FAIL on
  skills/acp-inbox-bridge/SKILL.md. The validator does still
  flag the pre-existing skills/acp-collab/SKILL.md (CRLF
  issue from the PR Add antianqi/openclaw-acp-bridge v0.1.3 - peer collaboration Bridge for MiniMax Code #3 round-1 fix that did not fully land);
  this PR does NOT touch acp-collab.
• python -c "import _acp_client; print('OK')": passes. The
  wrapper imports cleanly with the bundled client on the path.

The bundle was run locally on Windows + Python 3.14. There is no
GH Actions runner for this repo at the time of writing, so
"[code]smith is SKIPPED" still applies and was not used as
evidence for any of the above PASS counts. Same posture as
PR #3's R6.

Test evidence

End-to-end on Windows + Python 3.14, 2026-09-01 (Asia/Shanghai):

• mavis -> goudan (RAW fetch): 1-2 s
• mavis -> goudan (LLM with tool calls, audit + sessions):
  ~60 s for 32 tool calls + Chinese summary
• goudan -> mavis (proactive message via inbox): confirmed
  in inbox
• goudan distinguishes acp-integration (worker dispatch, the
  OpenClaw builtin) from acp-inbox-bridge (peer chat, this
  Skill): confirmed by goudan's own one-sentence summary
  after running the Skill on the new wrapper

The 401 negative cases (Check 14 and Check 15) and the
sender-filter delegation (Check 16) are direct round-trip
regressions on the goudan-side ACPInbox API; a future change
that accidentally bypasses the inherited _check_loopback or
the no-redirect opener will fail these at smoke time.

Design compliance

• No credentials. The wrapper reads the bearer token from
  the inherited _acp_client._resolve_token chain
  ($ACP_TOKEN -> ~/.acp_token -> <plugin_root>/.acp_token).
  No token default; no token literal anywhere in
  scripts/acp_inbox.py.
• No network beyond loopback. Every outbound call goes
  through the bundled client's _OPENER (loopback-only, no
  redirects). The wrapper's base_url parameter is validated
  against the inherited _check_loopback at construction; a
  non-loopback URL raises ACPError before any HTTP call.
• No telemetry. No print of message content, token, or
  base URL. CLI output is limited to the documented --action
  results.
• No third-party services. Stdlib only (urllib, json,
  os, sys, time, pathlib). No pip install, no npm install, no external SDK. The wrapper imports
  client/_acp_client from the same Plugin.
• No hardcoded paths. The wrapper resolves the plugin
  root through $ACP_PLUGIN_ROOT (set automatically by the
  Plugin runtime) with a __file__-based fallback. Verified
  by Check 10 and Check 11 of the smoke test.
• Single opener. The wrapper does not import
  urllib.request and does not call urlopen directly; all
  HTTP goes through _acp_client._request (which uses
  _OPENER). A future change that introduces a parallel
  urllib path will be caught by Check 8 of the smoke
  test.
• localhost is refused. The inherited _ALLOWED_HOSTS
  is the round-5 amendment literal-IP allow-list
  ({127.0.0.1, ::1, [::1]}). Check 6 of the smoke test
  asserts 'http://localhost:9999' is refused at the
  construction-time loopback check.
• Token is never logged / echoed. The CLI mode prints
  the URL, not the token. No print(token) anywhere.

Notes for the reviewer

• This PR was prepared on branch add-acp-inbox-bridge-skill
  in antianqi/MiniMax-Code-Plugins-1 on top of PR Add antianqi/openclaw-acp-bridge v0.1.3 - peer collaboration Bridge for MiniMax Code #3 head
  07c6358. It does not modify any file that PR Add antianqi/openclaw-acp-bridge v0.1.3 - peer collaboration Bridge for MiniMax Code #3's
  round-1 through round-5 reviews touched.
• The goudan_inbox_responder.py daemon mentioned in
  earlier ~/.openclaw/ paths is not part of this
  Plugin. It is the user's side daemon; this Plugin's
  goudan-side Skill is a separate, self-contained wrapper
  that the daemon can import if desired.
• The bundled client's inbox_* helpers do not accept a
  per-call base_url (they read $ACP_BASE_URL or fall
  back to DEFAULT_BASE_URL). The wrapper's base_url
  parameter is therefore a fail-fast validation on
  construction; the actual HTTP base URL is configured
  via the environment. This is documented in the wrapper
  docstring and in the SKILL.md "Setup" section.
• Stacked on PR Add antianqi/openclaw-acp-bridge v0.1.3 - peer collaboration Bridge for MiniMax Code #3: the diff vs main includes PR Add antianqi/openclaw-acp-bridge v0.1.3 - peer collaboration Bridge for MiniMax Code #3's
  6 review rounds. The reviewer's focused diff is the
  one against 07c6358 (PR Add antianqi/openclaw-acp-bridge v0.1.3 - peer collaboration Bridge for MiniMax Code #3 head).

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[hetaoBackend]

Current head a536628 passes the token-enabled wrapper smoke (36/36), the existing bridge smoke (24/24), no-redirect, compile and repository validation. Two public wrapper parameters do not work as documented: scripts/acp_inbox.py:117-123 validates and stores ACPInbox(base_url=...), but every method delegates to _acp_client.inbox_*, which reads $ACP_BASE_URL instead of self.base_url; an explicit constructor endpoint can therefore be ignored. Also ACPInbox.read() documents read(limit=...) at lines 168-180 but has no limit parameter and never forwards one, even though _acp_client.inbox_read supports it. Please make the wrapper endpoint and limit parameters effective (or remove them from the public contract) and add delegation tests that use different constructor/env URLs and assert the forwarded limit. [code]smith is SKIPPED.

[antianqi]

Round-7 fix on commits 00caf51 + 6ad7a00 + d999965 (rebased onto upstream/main)

@hetaoBackend Thanks for the round-7 review. Both blockers are now closed. The PR has also been rebased: the previous 12 commits on add-acp-inbox-bridge-skill were a v0.1.3 → v0.3.0 chain; PR #3 merged v0.2.0 in the meantime, which made 9 of those 12 commits obsolete (they were review fixes to the v0.1.3 baseline that v0.2.0 already incorporates). The branch is now a 3-commit chain on top of upstream/main (head a7f241b):

• 00caf51 — feat(openclaw-acp-bridge): add goudan-side acp-inbox-bridge skill (v0.3.0) — adds scripts/acp_inbox.py, scripts/test_inbox_goudan.py, skills/acp-inbox-bridge/SKILL.md, plus README / plugin.json updates for the goudan-side surface. The v0.2.0 baseline from PR Add antianqi/openclaw-acp-bridge v0.1.3 - peer collaboration Bridge for MiniMax Code #3 is the parent; no v0.1.3-only code is referenced.
• 6ad7a00 — fix(openclaw-acp-bridge): remove dead base_url, forward read(limit=) (PR #30 round-7) — the round-7 fix.
• d999965 (current head) — ci(openclaw-acp-bridge): also run test_inbox_goudan.py in the smoke workflow (PR #30 round-7 follow-up) — extends .github/workflows/openclaw-acp-bridge-smoke.yml to invoke test_inbox_goudan.py against the same live stub (one startup covers both mavis-side and goudan-side smokes). unset SMOKE_SKIP_LIVE is applied before the wrapper smoke so the wrapper's own CI fallback cannot degrade the live checks to skipped.

mergeable: MERGEABLE / mergeStateStatus: UNSTABLE (UNSTABLE is the [code]smith SKIPPED posture, not a content blocker).

base_url — removed from public contract

The bundled client's inbox_* helpers read $ACP_BASE_URL (or fall back to _acp_client.DEFAULT_BASE_URL); a per-instance base_url was silently ignored. Took the "remove from public contract" path rather than mutate os.environ in __init__ (side-effect) or change the bundled client (out of scope — that would touch round-1-approved code).

• ACPInbox.__init__ is now (default_timeout) only.
• The CLI (acp_inbox.py --action ping) no longer accepts --base-url; routing is via $ACP_BASE_URL. The CLI resolves the same env-var chain the bundled client uses and runs _check_loopback against the resolved value, so a non-loopback env is an instant FAIL with no HTTP round-trip.
• Check 4 in test_inbox_goudan.py is rewritten to pin the constructor's public surface to exactly ['default_timeout'] — a future change that re-introduces base_url= breaks this test.

read(limit=...) — now real

The docstring on read() advertised read(limit=...) but the parameter did not exist. Now:

def read(self, session_id, since_id=0, sender=None, msg_type=None, limit=None):
    return _acp_client.inbox_read(
        session_id=session_id, since_id=since_id,
        sender=sender, msg_type=msg_type, limit=limit,
    )

The bundled client's inbox_read already serializes limit to a limit=N query param and skips it when limit is None, so the wrapper is a pure "forward what's set" pass-through.

New test — Check 13b mocks _acp_client.inbox_read and asserts ACPInbox.read(limit=42) forwards limit=42 to the underlying call. Negative-injection: remove limit=limit, from acp_inbox.py:read() → Check 13b [FAIL] inbox_read was called with limit=42 (got None), rc=1, 30 pass / 1 fail / 8 skip. Restore → 31 pass / 0 fail / 8 skip. The test is structural, not false-green.

Validation

• python scripts/test_inbox_goudan.py --ci (SMOKE_SKIP_LIVE=1): 21 / 21 PASS, 0 FAIL, 10 SKIP (live checks gated).
• python scripts/test_inbox_goudan.py against the live stub (Windows + Python 3.14): 41 / 41 PASS, 0 FAIL, 0 SKIP. Includes Check 13b (read(limit=42) forwards), Check 4 (constructor surface pinned to default_timeout), and the rewritten CLI checks 21/22 (env-driven routing).
• python scripts/smoke.py (PR Add antianqi/openclaw-acp-bridge v0.1.3 - peer collaboration Bridge for MiniMax Code #3 mavis-side smoke, regression check): 26 / 26 PASS, 0 FAIL. Zero regression on the mavis side.
• python scripts/test_no_redirect.py: PASS. No-redirect guarantee still holds.
• node scripts/validate.mjs: no new FAIL on plugins/antianqi/openclaw-acp-bridge/. The pre-existing acp-collab CRLF issue is unchanged by this commit.
• Local CI step simulation of d999965: stub started with --token ci-test-token-xyzzy --port 19999, then python smoke.py and (after unset SMOKE_SKIP_LIVE) python test_inbox_goudan.py ran back-to-back. Wrapper smoke reported PASSED: 41, FAILED: 0, SKIPPED: 0, rc=0.

Why the 9 obsolete commits were dropped, not rebased

The original 12-commit branch's commits 2-10 (6d47fd3, 5231d38, 687a8c8, c79efc4, 9a0939b, 6e56ec4, b93669e, 07c6358) were review fixes against the v0.1.3 baseline. PR #3 (a7f241b) brought v0.2.0 to upstream/main and that version already incorporates the equivalent of every one of those review fixes (loopback guard hardened to literal-IP only, no-redirect opener shared with the smoke, bundled client replacing the SDK reference, health() routing, localhost removed from the allow-list, CI workflow added, smoke refusal of non-loopback ACP_BASE_URL, auth docs aligned). Cherry-picking them on top of v0.2.0 produced 5+ add/add or content conflicts on the same files the rebase is touching. The clean history is 3 commits: the goudan-side surface, the round-7 fix, and the CI follow-up. No v0.1.3-only content is reintroduced; the v0.2.0 baseline from PR #3 is preserved end-to-end.

Re-requesting review.