Add Lark document comment Connector provider

[huangruiteng]

Summary

• add the first concrete Lark document-comment adapter for the Agent external Connector runtime introduced by Add Agent-scoped external Connector runtime #3483
• bind one owner-local document target, CLI profile, and bot or user identity without persisting private routing data in public state
• paginate comment cards and nested replies with restart-safe private cursors and stable hashed event identities
• require exact comment scopes and verify that permission probes use the same identity as provider reads and writes
• create replies through an owner-local idempotency receipt, verify exact readback, and let the generic runtime ACK only after durable Agent effect plus verified provider response
• reject unsupported addressed-only inference and filter comment surfaces that cannot accept replies

Public/private boundary

The repository contains no document URLs, profile values, credentials, raw provider payloads, comment or reply identifiers, cursors, or response bodies. Concrete targets and reply receipts remain owner-local. Missing publication or scopes fail closed with content-free repair guidance.

Real adapter evidence

A bounded read-only call against an owner-configured document completed through the concrete CLI adapter and returned one event page with a bound continuation cursor. A separate bot-identity probe correctly returned missing comment requirements instead of being misclassified as a malformed permission response. No external reply was posted during validation.

Validation

• pytest -q tests/extensions — 435 passed
• focused runtime, Provider, and document-comment tests — 34 passed
• Ruff check and changed-file compile — passed
• loopx canary premerge --from-git-diff --git-diff-base origin/main --goal-id <managed-goal> — passed, including public-boundary and extension-runtime risk checks
• git diff --check origin/main...HEAD — passed

Merge decision

This changes external reads, writes, permissions, receipts, and ACK behavior. It requires independent review and will not be self-merged by the author.

[sonarqubecloud]

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[huangruiteng]

Independent maintainer self-review and pre-merge qualification

Reviewed and refined exact head af03122f4bb7f90240bd71af64d7c613249c91fc. GitHub does not allow an author to formally approve their own PR, so this comment records the independent review evidence and the owner-authorized admin-bypass merge decision.

Findings fixed during review

• Restored the exact ephemeral idempotency_key binding required by generic Connector settlement. The original head returned only its digest, which caused the full pytest job to fail (1 failed, 3980 passed, 10 skipped). Public settlement still reduces this to the safe digest form.
• Corrected the provider-neutral capture contract: a polled document comment is no longer marked addressed=true merely because the provider observed it. This keeps explicit routing/addressing authority outside the transport adapter.
• Closed the create-before-receipt crash window. The provider now persists a creating intent before the external effect, attaches a LoopX idempotency marker, performs bounded reply recovery on replay, and fails closed instead of blindly posting a duplicate.
• Declared lark-cli >= 1.0.69, the first compatible release that exposes drive +list-comments; added read-only command validation against the current CLI.
• Tightened timestamp/type handling and the changed module's typed-helper boundary.

Placement and bounded future-facing pass

• Capability owner: the provider-neutral Agent external Connector runtime.
• Provider owner: the built-in loopx-lark extension adapter in loopx/extensions/lark; no new capability or speculative framework was added.
• The provider reuses the generic registration, capture, settlement, permission, locking, and owner-local atomic-write contracts.
• The related future-facing pass was applied: duplicate reply pagination/recovery logic was consolidated behind one bounded iterator and one receipt state machine. A broader CLI/wiring expansion was deliberately deferred because this PR ships a concrete injectable provider contract without needing another public surface.

Validation

• GitHub required checks: full pytest, Windows PowerShell lifecycle, DCO sign-off, dependency review, SonarCloud, and both release/frontstage builds passed on the exact head. Non-release deploy, package upload, and PyPI publication jobs were skipped as expected.
• pytest tests/extensions: 437 passed.
• Focused provider plus generic call-site regression set: 17 passed, including create-success/crash-before-receipt recovery without a second create.
• ruff check, ruff format --check, compileall, and git diff --check: passed.
• Exact changed-module mypy (--follow-imports=skip): passed. A diagnostic full imported-module traversal still exposes 21 pre-existing errors in untouched authority/file-lock modules; none are introduced by this diff.
• loopx check on the exact four changed public paths: no errors. Four registry-wide projection warnings remain outside this diff.
• lark-cli compatibility: local 1.0.68 correctly rejects drive +list-comments; current 1.0.89 accepts the documented command in --dry-run. No external Lark write was performed.
• loopx canary premerge --from-git-diff: 14/14 selected checks passed, 0 manual holds, self-merge allowed.
• Change-quality receipt cqr_f102c322b78012d0cc11: pass, exact diff fingerprint f102c322b78012d0cc11c9d355678d8417b5aa5b1ce0d1105f6e541c33f9c142, safe fix applied, 0 blockers.

Authority, privacy, and coverage judgment

The extension is limited to the configured document-comment read/create scopes. Document URLs, profiles, cursors, and recovery receipts remain owner-local; provider payloads and credentials are not projected into public status. No real document reply was posted during qualification: mocked lifecycle tests cover create/readback/ACK/replay semantics, while the read-only CLI dry-run verifies the shipped command surface. Together with the full repository test matrix, Windows lifecycle check, exact diff canary, permission boundaries, and crash-recovery regression, this is sufficient coverage for this provider adapter.

Conclusion: approved after refinement. No unresolved blocker or manual hold remains; owner-authorized admin-bypass squash merge is appropriate.