feat(browser-act): API-key credentials + packs endpoint + frontend surfacing (PR-E)

Credentials (decision #7): BrowserActChannel resolves a stored key via the
existing encrypted AuthManager.resolve(source_id) path (key_name
"browser_act_api_key") and injects it into the browser-act subprocess env
(BROWSER_ACT_API_KEY). stealth mode without a resolvable key is a hard, loud
error — never a silent fallback to chrome-direct, never keyless. The key never
enters ChannelResult.error/.metadata/logs.

Threading source_id required a narrow fetch() override: AbstractChannel's
default fetch() bridge drops ctx.source_id, so without this the stealth key
would be silently unresolvable in production runs. collect() gains an additive
optional source_id (direct calls stay best-effort). Documented trade-off: the
override makes channel_runner build an unused httpx client (no socket opened).

Endpoint: GET /api/v1/browser-act/packs (read-only PackCatalog listing with
per-pack has_manifest + param_schema; invalid manifest -> has_manifest=false,
never 500; no credential ever in scope).

Frontend (decision #9, minimal): channel_type union + BrowserActPack type +
"BrowserAct 采集" label + listBrowserActPacks/useBrowserActPacks hooks (the
frontend has no source-creation form yet, so the hooks are wired but unconsumed,
matching the existing createSource status). tsc --noEmit + eslint clean.

12 tests (encrypt round-trip + env injection, stealth-missing-key error,
chrome-direct keyless ok, no-leak, fetch() source_id path, packs endpoint).
1492 -> 1504 passed, zero regression (full suite verified). Completes GOAL-7.

Author: 2233admin

backend/api/v1/__init__.py

@@ -4,6 +4,7 @@
 
 from backend.api.v1 import (
     agents,
+    browser_act,
     browsers,
     chat,
     control,
@@ -31,6 +32,7 @@
 v1_router = APIRouter(prefix="/api/v1")
 
 v1_router.include_router(agents.router)
+v1_router.include_router(browser_act.router)
 v1_router.include_router(browsers.router)
 v1_router.include_router(chat.router)
 v1_router.include_router(control.router)

backend/api/v1/browser_act.py

@@ -0,0 +1,84 @@
+"""GET /api/v1/browser-act/packs — read-only catalog listing for the
+BrowserAct channel's frontend surfacing (GOAL-7 PR-E, decision #9).
+
+Reuses ``PackCatalog`` (PR-A) + ``load_manifest`` (PR-A schema / PR-D seeds)
+— no new catalog mechanism, no DB table. Read-only, no auth (matches the
+admin-tool style of the other v1 routers, e.g. providers.py/presets.py).
+
+Never exposes anything from ``SourceCredential``/``AuthManager``: this is a
+static vendored-file catalog listing (name/description/category/domain/
+capability/path/has_manifest/param_schema) — there is no per-source config
+or credential in scope here at all, so there is nothing to leak.
+"""
+
+import logging
+from json import JSONDecodeError
+from typing import Any
+
+from fastapi import APIRouter
+from pydantic import BaseModel, ValidationError
+
+from backend.browser_act_packs.catalog import PackCatalog
+from backend.browser_act_packs.manifest import load_manifest
+from backend.schemas.common import ApiResponse
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/browser-act", tags=["browser-act"])
+
+
+class BrowserActPackRead(BaseModel):
+    """One catalogued pack + its manifest status, for the sources UI's
+    preset dropdown (decision #9). ``param_schema`` is the manifest's own
+    ``param_schema`` (``ParamSpec``-shaped dicts) when ``has_manifest`` is
+    True, else empty — a missing/invalid manifest is a valid catalog entry,
+    never a 500 (mirrors ``BrowserActChannel._load_pack_manifest``'s
+    guard-don't-crash contract)."""
+
+    name: str
+    description: str = ""
+    category: str
+    domain: str
+    capability: str
+    path: str
+    has_manifest: bool
+    param_schema: list[dict[str, Any]] = []
+
+
+@router.get("/packs", response_model=ApiResponse[list[BrowserActPackRead]])
+async def list_packs() -> ApiResponse:
+    """List every vendored browser-act pack the catalog can see, each
+    annotated with whether it has a machine-readable ``channel.manifest.json``
+    yet (PR-D seeded 2 of the ~78 vendored packs; the rest are catalog-only
+    until a future manifest is authored for them)."""
+    catalog = PackCatalog()
+    packs: list[BrowserActPackRead] = []
+    for info in catalog.list_packs():
+        manifest_path = catalog.root / info.path / "channel.manifest.json"
+        has_manifest = manifest_path.exists()
+        param_schema: list[dict[str, Any]] = []
+        if has_manifest:
+            try:
+                manifest = load_manifest(manifest_path)
+                param_schema = [p.model_dump() for p in manifest.param_schema]
+            except (JSONDecodeError, ValidationError) as exc:
+                logger.warning(
+                    "browser-act packs endpoint: pack %s has an invalid "
+                    "channel.manifest.json, reporting has_manifest=false: %s",
+                    info.path,
+                    exc,
+                )
+                has_manifest = False
+        packs.append(
+            BrowserActPackRead(
+                name=info.name,
+                description=info.description,
+                category=info.category,
+                domain=info.domain,
+                capability=info.capability,
+                path=info.path,
+                has_manifest=has_manifest,
+                param_schema=param_schema,
+            )
+        )
+    return ApiResponse.ok(packs)

backend/channels/browser_act_channel.py

@@ -1,5 +1,6 @@
 """BrowserActChannel — the generic browser-act pack manifest interpreter
-(GOAL-7 PR-C; see GOAL-7.md architecture decisions #1, #4, #5, #6, #8, #10).
+(GOAL-7 PR-C/PR-E; see GOAL-7.md architecture decisions #1, #4, #5, #6, #7,
+#8, #10).
 
 Drives a vendored pack (backend/browser_act_packs/<category>/<pack>/,
 PR-A) through its channel.manifest.json (PR-A schema, backend/
@@ -29,6 +30,16 @@
 (``"result_count < N"`` / ``"<="``). Anything else falls back to a fixed
 ``max_pages`` cap and an "a page returned 0 items" stop signal -- documented
 limitation, not silently pretended to be complete (see ``_stop_when_triggered``).
+
+Credentials (PR-E, decision #7): ``mode == "stealth"`` requires a BrowserAct
+API key, stored encrypted as a ``SourceCredential`` (key_name
+``CREDENTIAL_KEY_NAME``) and resolved via the existing ``AuthManager``
+(same encrypted store every other channel's credentials go through --
+``_resolve_session_env``). It is injected into the browser-act CLI
+subprocess env (never argv, never logged) under ``BROWSER_ACT_API_KEY_ENV``.
+``collect()`` takes an additive optional ``source_id`` param for this; only
+``fetch()`` (the thick-contract entry point ``run_channel`` calls) ever
+passes a real one in production -- see both methods' docstrings.
 """
 
 import json
@@ -43,7 +54,14 @@
 from backend.browser_act.scripts import ScriptError, run_pack_script
 from backend.browser_act_packs.catalog import PackCatalog, PackInfo
 from backend.browser_act_packs.manifest import PackManifest, load_manifest
-from backend.channels.base import AbstractChannel, Capabilities, ChannelResult
+from backend.channels.base import (
+    AbstractChannel,
+    Capabilities,
+    ChannelFetchError,
+    ChannelResult,
+    FetchContext,
+    FetchResult,
+)
 from backend.channels.registry import register_channel
 
 logger = logging.getLogger(__name__)
@@ -80,6 +98,26 @@
 #: taobao-keyword-search's "result count < 10") is understood.
 _STOP_WHEN_RE = re.compile(r"result_count\s*(<=|<)\s*(\d+)")
 
+#: SourceCredential key_name the BrowserAct API key is stored under (decision
+#: #7). Resolved via the existing AuthManager.resolve(source_id) pattern --
+#: same encrypted store api_channel.py / crawl4ai_channel.py already use, no
+#: new credential path.
+CREDENTIAL_KEY_NAME = "browser_act_api_key"
+
+#: Env var the resolved key is injected under for the browser-act CLI
+#: subprocess (BrowserActSession's ``env``, see backend.browser_act.cli).
+#: The upstream CLI's own docs (browser-act-skills/docs/installation.md)
+#: only document a persistent local auth store -- ``browser-act auth set
+#: <key>`` / ``auth login`` / ``auth poll`` -- and never mention an env var
+#: for feeding a key non-interactively; there is no live browser-act binary
+#: in this environment to confirm one against. This name is this PR's
+#: documented assumption (most likely candidate), chosen to match the
+#: existing BROWSER_ACT_BIN / browser_act_timeout naming convention already
+#: in this codebase -- and PR-C's own test (test_secret_not_leaked_in_error)
+#: and BrowserActError's docstring ("PR-C injects secrets ... via env")
+#: already anticipated exactly this name.
+BROWSER_ACT_API_KEY_ENV = "BROWSER_ACT_API_KEY"
+
 
 def _classify_error(message: str) -> str:
     """Classify a pack script's reported error message.
@@ -192,6 +230,49 @@ def _load_pack_manifest(
             )
         return pack_dir, manifest, None
 
+    @staticmethod
+    async def _resolve_session_env(
+        source_id: str | None, mode: str
+    ) -> tuple[dict[str, str] | None, str | None]:
+        """Resolve the stored BrowserAct API key (decision #7,
+        ``CREDENTIAL_KEY_NAME``) into subprocess env for the browser-act CLI
+        hop, via ``AuthManager.resolve(source_id)`` -- the same encrypted-
+        store pattern ``ApiChannel._resolve_auth_headers`` /
+        ``Crawl4AIChannel._resolve_cookies`` already use; no new credential
+        path.
+
+        Returns ``(session_env, error)``:
+
+        - ``error`` is set only when ``mode == "stealth"`` and no key could
+          be resolved -- stealth REQUIRES a key and must never silently fall
+          back to chrome-direct or run keyless (decision #7 DoD).
+        - ``chrome-direct`` never errors here: a resolved key, if any, is
+          still injected (harmless -- browser-act simply doesn't need it),
+          but its absence is fine.
+
+        ``source_id`` is ``None`` when ``collect()`` is called directly
+        (bypassing the runner). That is treated identically to "no key
+        stored" -- best-effort resolution, not a fabricated source id (see
+        ``collect()``'s docstring and ``fetch()`` below, the only path that
+        ever has a real one in production).
+        """
+        key: str | None = None
+        if source_id:
+            from backend.auth.manager import AuthManager
+
+            creds = await AuthManager().resolve(source_id)
+            key = creds.get(CREDENTIAL_KEY_NAME)
+
+        if mode == "stealth" and not key:
+            return None, (
+                "stealth mode requires a BrowserAct API key "
+                f"(store it as {CREDENTIAL_KEY_NAME})"
+            )
+
+        if key:
+            return {BROWSER_ACT_API_KEY_ENV: key}, None
+        return None, None
+
     async def validate_config(self, config: dict[str, Any]) -> list[str]:
         """Validate channel_config; only checks what config alone can prove:
         pack resolvability, mode legality, and required params NOT
@@ -226,8 +307,20 @@ async def validate_config(self, config: dict[str, Any]) -> list[str]:
     # ── collect() ────────────────────────────────────────────────────────
 
     async def collect(
-        self, config: dict[str, Any], parameters: dict[str, Any]
+        self,
+        config: dict[str, Any],
+        parameters: dict[str, Any],
+        source_id: str | None = None,
     ) -> ChannelResult:
+        """``source_id`` is an additive optional param beyond the
+        ``AbstractChannel.collect(config, parameters)`` contract (legal --
+        ABC only requires the method exist, not an exact signature): a
+        direct call (tests, or any future non-source-scoped caller) omits it
+        and gets best-effort credential resolution (chrome-direct works
+        keyless; stealth still requires a key, see ``_resolve_session_env``).
+        ``fetch()`` below is this channel's only production path that ever
+        has a real value to pass -- ``run_channel`` populates
+        ``FetchContext.source_id`` from the real ``DataSource.id``."""
         pack_info, pack_error = self._resolve_pack_info(config)
         if pack_error:
             return ChannelResult(success=False, error_type="error", error=pack_error)
@@ -264,10 +357,14 @@ async def collect(
 
         max_pages = config.get("max_pages") or _DEFAULT_MAX_PAGES
 
-        # Credential injection is PR-E's job (decision #7: SourceCredential /
-        # AuthManager, key_name="browser_act_api_key"). This hook exists so
-        # PR-E only has to fill session_env -- the loop below doesn't change.
-        session_env: dict[str, str] | None = None
+        # Credential injection (decision #7): resolve the stored BrowserAct
+        # API key via the existing AuthManager.resolve(source_id) pattern and
+        # inject it into the browser-act subprocess env. stealth mode without
+        # a resolvable key is a hard, loud error here -- it never silently
+        # falls back to chrome-direct and never runs keyless.
+        session_env, cred_error = await self._resolve_session_env(source_id, mode)
+        if cred_error:
+            return ChannelResult(success=False, error_type="error", error=cred_error)
         session_name = f"browser-act-{pack_info.domain}-{pack_info.capability}"
 
         items: list[dict[str, Any]] = []
@@ -354,6 +451,37 @@ async def collect(
             metadata={"pack": pack_info.path, "pages_fetched": pages_fetched, "mode": mode},
         )
 
+    async def fetch(self, ctx: FetchContext) -> FetchResult:
+        """Thick-contract entry point, overridden narrowly (decision #7):
+        ``AbstractChannel``'s default ``fetch()`` bridges straight to
+        ``collect(ctx.config, ctx.params)`` and drops ``ctx.source_id`` on
+        the floor -- every other collect()-only channel (including this
+        one before PR-E) is fine with that. Credential resolution needs the
+        real ``DataSource.id`` though, and ``run_channel`` (backend.pipeline.
+        channel_runner) is the only place that ever has one -- so this
+        override exists solely to thread ``ctx.source_id`` through to
+        ``collect()``. A direct ``collect()`` call (tests, or any future
+        caller outside the runner) still works, just chrome-direct-only /
+        best-effort on stealth (see ``_resolve_session_env``).
+
+        Documented trade-off: overriding ``fetch()`` flips
+        ``channel_runner.run_channel``'s ``channel_migrated`` check, so the
+        runner builds a ``RateLimitedClient``/``httpx.AsyncClient`` for this
+        channel's run and tears it down afterward even though this channel
+        never reads ``ctx.http`` (browser-act drives its own subprocess, not
+        HTTP). Accepted deliberately: ``httpx.AsyncClient()`` never opens a
+        real connection until first used, so the unused cost here is one
+        Python object for the run's duration, not an open socket -- real
+        credential resolution matters more than avoiding that.
+        """
+        result = await self.collect(ctx.config, ctx.params, source_id=ctx.source_id)
+        if not result.success:
+            raise ChannelFetchError(
+                result.error or f"{self.channel_type} collect failed",
+                error_type=result.error_type,
+            )
+        return FetchResult(items=result.items, metadata=result.metadata)
+
     async def _run_page(
         self,
         sess: Any,

frontend/app/(app)/sources/page.tsx

@@ -34,6 +34,7 @@ const CHANNEL_LABEL: Record<DataSource['channel_type'], string> = {
   cli: 'CLI',
   skill: '技能',
   crawl4ai: 'Crawl4AI',
+  browser_act: 'BrowserAct 采集',
 }
 
 export default function SourcesPage() {

frontend/lib/api/endpoints.ts

@@ -4,6 +4,7 @@ import type {
   AdvisoryReport,
   ApiResponse,
   ModelProvider,
+  BrowserActPack,
   BrowserBinding,
   ChromeEndpoint,
   CollectedRecord,
@@ -380,6 +381,12 @@ export const updateChromeEndpointMode = (endpoint: string, mode: 'bridge' | 'cdp
 export const listPresets = () =>
   apiClient.get<ApiResponse<PresetsGrouped>>('/presets').then((r) => r.data.data)
 
+// ── BrowserAct packs (GOAL-7 PR-E, decision #9) ─────────────────────────────────
+// Read-only vendored-pack catalog for the 'browser_act' channel's one-click
+// config preset (pack picker) — never carries a credential/api_key.
+export const listBrowserActPacks = () =>
+  apiClient.get<ApiResponse<BrowserActPack[]>>('/browser-act/packs').then((r) => r.data.data)
+
 // ── Plans (Plan IR issue 02) — Collection Canvas persistence ────────────────────
 // Save (create/update) validates server-side and 422s with a node-anchored
 // error list (backend.plan_ir.validation.PlanValidationError.to_dict()) on an

frontend/lib/api/hooks.ts

@@ -62,6 +62,14 @@ export function usePresets() {
   })
 }
 
+export function useBrowserActPacks() {
+  return useQuery({
+    queryKey: ['browser-act-packs'],
+    queryFn: () => api.listBrowserActPacks(),
+    staleTime: 5 * 60_000,
+  })
+}
+
 export function usePlans(params?: { draft?: boolean; page?: number; limit?: number }) {
   return useQuery({
     queryKey: ['plans', params],

frontend/lib/api/types.ts

@@ -43,7 +43,7 @@ export interface DataSource {
   id: string
   name: string
   description?: string
-  channel_type: 'opencli' | 'web_scraper' | 'api' | 'rss' | 'cli' | 'skill' | 'crawl4ai'
+  channel_type: 'opencli' | 'web_scraper' | 'api' | 'rss' | 'cli' | 'skill' | 'crawl4ai' | 'browser_act'
   channel_config: Record<string, unknown>
   ai_config?: Record<string, unknown>
   enabled: boolean
@@ -732,3 +732,24 @@ export interface PlanHealthRead {
   detail: Record<string, unknown>
   recorded_at: string
 }
+
+// ── BrowserAct packs (GOAL-7 PR-E, decision #9) ──────────────────────────────
+// Mirrors backend.api.v1.browser_act.BrowserActPackRead. Read-only vendored
+// pack catalog for the 'browser_act' channel's config preset — never carries
+// any credential/api_key (the BrowserAct API key is a SourceCredential,
+// configured through the existing credential UI, not through pack config).
+export interface BrowserActPack {
+  name: string
+  description: string
+  category: string
+  domain: string
+  capability: string
+  path: string
+  has_manifest: boolean
+  param_schema: Array<{
+    name: string
+    required: boolean
+    default?: string | null
+    enum?: string[] | null
+  }>
+}