Auto-merge upstream openclaw/openclaw

Author: friuns2

docs/AGENTS.md

@@ -0,0 +1,28 @@
+# Docs Guide
+
+This directory owns docs authoring, Mintlify link rules, and docs i18n policy.
+
+## Mintlify Rules
+
+- Docs are hosted on Mintlify (`https://docs.openclaw.ai`).
+- Internal doc links in `docs/**/*.md` must stay root-relative with no `.md` or `.mdx` suffix (example: `[Config](/configuration)`).
+- Section cross-references should use anchors on root-relative paths (example: `[Hooks](/configuration#hooks)`).
+- Doc headings should avoid em dashes and apostrophes because Mintlify anchor generation is brittle there.
+- README and other GitHub-rendered docs should keep absolute docs URLs so links work outside Mintlify.
+- Docs content must stay generic: no personal device names, hostnames, or local paths; use placeholders like `user@gateway-host`.
+
+## Docs Content Rules
+
+- For docs, UI copy, and picker lists, order services/providers alphabetically unless the section is explicitly describing runtime order or auto-detection order.
+- Keep bundled plugin naming consistent with the repo-wide plugin terminology rules in the root `AGENTS.md`.
+
+## Docs i18n
+
+- Foreign-language docs are not maintained in this repo. The generated publish output lives in the separate `openclaw/docs` repo (often cloned locally as `../openclaw-docs`).
+- Do not add or edit localized docs under `docs/<locale>/**` here.
+- Treat English docs in this repo plus glossary files as the source of truth.
+- Pipeline: update English docs here, update `docs/.i18n/glossary.<locale>.json` as needed, then let the publish-repo sync and `scripts/docs-i18n` run in `openclaw/docs`.
+- Before rerunning `scripts/docs-i18n`, add glossary entries for any new technical terms, page titles, or short nav labels that must stay in English or use a fixed translation.
+- `pnpm docs:check-i18n-glossary` is the guard for changed English doc titles and short internal doc labels.
+- Translation memory lives in generated `docs/.i18n/*.tm.jsonl` files in the publish repo.
+- See `docs/.i18n/README.md`.

docs/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

docs/plugins/architecture.md

@@ -527,6 +527,9 @@ actual behavior such as hooks, tools, commands, or provider flows.
 Optional manifest `activation` and `setup` blocks stay on the control plane.
 They are metadata-only descriptors for activation planning and setup discovery;
 they do not replace runtime registration, `register(...)`, or `setupEntry`.
+The first activation consumer now uses manifest command hints to narrow CLI
+plugin loading when a primary command is known, instead of always loading every
+CLI-capable plugin up front.
 
 Setup discovery now prefers descriptor-owned ids such as `setup.providers` and
 `setup.cliBackends` to narrow candidate plugins before it falls back to

docs/plugins/manifest.md

@@ -221,6 +221,9 @@ should activate it later.
 
 This block is metadata only. It does not register runtime behavior, and it does
 not replace `register(...)`, `setupEntry`, or other runtime/plugin entrypoints.
+Current consumers use it as a narrowing hint before broader plugin loading, so
+missing activation metadata only costs performance; it should not change
+correctness.
 
 ```json
 {
@@ -242,6 +245,10 @@ not replace `register(...)`, `setupEntry`, or other runtime/plugin entrypoints.
 | `onRoutes`       | No       | `string[]`                                           | Route kinds that should activate this plugin.                     |
 | `onCapabilities` | No       | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Broad capability hints used by control-plane activation planning. |
 
+For command-triggered planning specifically, OpenClaw still falls back to
+legacy `commandAliases[].cliCommand` or `commandAliases[].name` when a plugin
+has not added explicit `activation.onCommands` metadata yet.
+
 ## setup reference
 
 Use `setup` when setup and onboarding surfaces need cheap plugin-owned metadata

extensions/AGENTS.md

@@ -51,6 +51,15 @@ third-party plugins see.
   provider needs OpenAI-style Anthropic tool payload compat, Gemini schema
   cleanup, or an XAI compat patch, use a named shared helper instead of
   inlining the policy knobs again.
+- Keep control-plane metadata separate from runtime logic. Discovery, config
+  validation, setup hints, onboarding hints, and activation planning should be
+  expressible from manifest/descriptors whenever possible.
+- If setup truly requires runtime execution, make that explicit in the plugin's
+  declared setup/runtime surface instead of letting metadata flows import
+  runtime code accidentally.
+- Do not rely on eager global registry seeding or import-time side effects to
+  make a plugin “available”. Plugin availability should come from manifest
+  ownership plus targeted activation.
 
 ## Expanding The Boundary
 

extensions/browser/src/browser/routes/agent.act.existing-session-navigation-guard.test.ts

@@ -1,23 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createExistingSessionAgentSharedModule } from "./existing-session.test-support.js";
 import { createBrowserRouteApp, createBrowserRouteResponse } from "./test-helpers.js";
-import type { BrowserRequest } from "./types.js";
-
-const routeState = vi.hoisted(() => ({
-  profileCtx: {
-    profile: {
-      driver: "existing-session" as const,
-      name: "chrome-live",
-    },
-    ensureTabAvailable: vi.fn(async () => ({
-      targetId: "7",
-      url: "https://example.com",
-    })),
-  },
-  tab: {
-    targetId: "7",
-    url: "https://example.com",
-  },
-}));
 
 const chromeMcpMocks = vi.hoisted(() => ({
   clickChromeMcpElement: vi.fn(async () => {}),
@@ -49,26 +32,7 @@ vi.mock("../chrome-mcp.js", () => ({
 
 vi.mock("../navigation-guard.js", () => navigationGuardMocks);
 
-vi.mock("./agent.shared.js", () => ({
-  getPwAiModule: vi.fn(async () => null),
-  handleRouteError: vi.fn(),
-  readBody: vi.fn((req: BrowserRequest) => req.body ?? {}),
-  requirePwAi: vi.fn(async () => {
-    throw new Error("Playwright should not be used for existing-session tests");
-  }),
-  resolveProfileContext: vi.fn(() => routeState.profileCtx),
-  resolveTargetIdFromBody: vi.fn((body: Record<string, unknown>) =>
-    typeof body.targetId === "string" ? body.targetId : undefined,
-  ),
-  withPlaywrightRouteContext: vi.fn(),
-  withRouteTabContext: vi.fn(async ({ run }: { run: (args: unknown) => Promise<void> }) => {
-    await run({
-      profileCtx: routeState.profileCtx,
-      cdpUrl: "http://127.0.0.1:18800",
-      tab: routeState.tab,
-    });
-  }),
-}));
+vi.mock("./agent.shared.js", () => createExistingSessionAgentSharedModule());
 
 const DEFAULT_SSRF_POLICY = { allowPrivateNetwork: false } as const;
 
@@ -119,6 +83,31 @@ describe("existing-session interaction navigation guard", () => {
     return response;
   }
 
+  async function expectActionToReject(body: Record<string, unknown>) {
+    const handler = getActPostHandler();
+    const response = createBrowserRouteResponse();
+    const pending = handler?.({ params: {}, query: {}, body }, response.res) ?? Promise.resolve();
+    void pending.catch(() => {});
+    const completion = (async () => {
+      await vi.runAllTimersAsync();
+      await pending;
+    })();
+
+    await expect(completion).rejects.toThrow("Unable to verify stable post-interaction navigation");
+  }
+
+  function expectNavigationProbeUrls(urls: string[]) {
+    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenCalledTimes(
+      urls.length,
+    );
+    for (const [index, url] of urls.entries()) {
+      expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
+        index + 1,
+        expect.objectContaining({ url }),
+      );
+    }
+  }
+
   it("checks navigation after click and key-driven submit paths", async () => {
     const clickResponse = await runAction({ kind: "click", ref: "btn-1" });
     const typeResponse = await runAction({
@@ -134,31 +123,7 @@ describe("existing-session interaction navigation guard", () => {
     expect(chromeMcpMocks.pressChromeMcpKey).toHaveBeenCalledWith(
       expect.objectContaining({ key: "Enter" }),
     );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenCalledTimes(6);
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      1,
-      expect.objectContaining({ url: "https://example.com" }),
-    );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      2,
-      expect.objectContaining({ url: "https://example.com" }),
-    );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      3,
-      expect.objectContaining({ url: "https://example.com" }),
-    );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      4,
-      expect.objectContaining({ url: "https://example.com" }),
-    );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      5,
-      expect.objectContaining({ url: "https://example.com" }),
-    );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      6,
-      expect.objectContaining({ url: "https://example.com" }),
-    );
+    expectNavigationProbeUrls(Array.from({ length: 6 }, () => "https://example.com"));
   });
 
   it("rechecks the page url after delayed navigation-triggering interactions", async () => {
@@ -172,18 +137,11 @@ describe("existing-session interaction navigation guard", () => {
 
     expect(response.statusCode).toBe(200);
     expect(chromeMcpMocks.evaluateChromeMcpScript).toHaveBeenCalledTimes(4);
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      1,
-      expect.objectContaining({ url: "https://example.com" }),
-    );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      2,
-      expect.objectContaining({ url: "http://169.254.169.254/latest/meta-data/" }),
-    );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      3,
-      expect.objectContaining({ url: "http://169.254.169.254/latest/meta-data/" }),
-    );
+    expectNavigationProbeUrls([
+      "https://example.com",
+      "http://169.254.169.254/latest/meta-data/",
+      "http://169.254.169.254/latest/meta-data/",
+    ]);
   });
 
   it("fails closed when location probes never return a usable url", async () => {
@@ -193,20 +151,7 @@ describe("existing-session interaction navigation guard", () => {
       .mockResolvedValueOnce(null as never)
       .mockResolvedValueOnce("   " as never);
 
-    const handler = getActPostHandler();
-    const response = createBrowserRouteResponse();
-    const pending =
-      handler?.(
-        { params: {}, query: {}, body: { kind: "evaluate", fn: "() => 1" } },
-        response.res,
-      ) ?? Promise.resolve();
-    void pending.catch(() => {});
-    const completion = (async () => {
-      await vi.runAllTimersAsync();
-      await pending;
-    })();
-
-    await expect(completion).rejects.toThrow("Unable to verify stable post-interaction navigation");
+    await expectActionToReject({ kind: "evaluate", fn: "() => 1" });
     expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).not.toHaveBeenCalled();
   });
 
@@ -218,24 +163,8 @@ describe("existing-session interaction navigation guard", () => {
       .mockResolvedValueOnce(undefined as never) // location probe 3 - unreadable
       .mockResolvedValueOnce(undefined as never); // follow-up probe - still unreadable
 
-    const handler = getActPostHandler();
-    const response = createBrowserRouteResponse();
-    const pending =
-      handler?.(
-        { params: {}, query: {}, body: { kind: "evaluate", fn: "() => 1" } },
-        response.res,
-      ) ?? Promise.resolve();
-    void pending.catch(() => {});
-    const completion = (async () => {
-      await vi.runAllTimersAsync();
-      await pending;
-    })();
-
-    await expect(completion).rejects.toThrow("Unable to verify stable post-interaction navigation");
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenCalledOnce();
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenCalledWith(
-      expect.objectContaining({ url: "https://example.com" }),
-    );
+    await expectActionToReject({ kind: "evaluate", fn: "() => 1" });
+    expectNavigationProbeUrls(["https://example.com"]);
   });
 
   it("confirms stability via follow-up probe when URL changes on the last loop iteration", async () => {
@@ -256,19 +185,11 @@ describe("existing-session interaction navigation guard", () => {
     expect(response.statusCode).toBe(200);
     // 1 action call + 5 location probes (3 in loop + 1 failed + 1 follow-up)
     expect(chromeMcpMocks.evaluateChromeMcpScript).toHaveBeenCalledTimes(5);
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenCalledTimes(3);
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      1,
-      expect.objectContaining({ url: "https://example.com" }),
-    );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      2,
-      expect.objectContaining({ url: "https://safe-redirect.com" }),
-    );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      3,
-      expect.objectContaining({ url: "https://safe-redirect.com" }),
-    );
+    expectNavigationProbeUrls([
+      "https://example.com",
+      "https://safe-redirect.com",
+      "https://safe-redirect.com",
+    ]);
   });
 
   it("keeps probing through the full window before declaring navigation stable", async () => {
@@ -283,23 +204,12 @@ describe("existing-session interaction navigation guard", () => {
 
     expect(response.statusCode).toBe(200);
     expect(chromeMcpMocks.evaluateChromeMcpScript).toHaveBeenCalledTimes(5);
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenCalledTimes(4);
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      1,
-      expect.objectContaining({ url: "https://example.com" }),
-    );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      2,
-      expect.objectContaining({ url: "https://example.com" }),
-    );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      3,
-      expect.objectContaining({ url: "https://safe-redirect.com" }),
-    );
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenNthCalledWith(
-      4,
-      expect.objectContaining({ url: "https://safe-redirect.com" }),
-    );
+    expectNavigationProbeUrls([
+      "https://example.com",
+      "https://example.com",
+      "https://safe-redirect.com",
+      "https://safe-redirect.com",
+    ]);
   });
 
   it("fails closed when follow-up probe sees yet another URL change", async () => {
@@ -310,20 +220,7 @@ describe("existing-session interaction navigation guard", () => {
       .mockResolvedValueOnce("https://c.com" as never) // location probe 3: changed again
       .mockResolvedValueOnce("https://d.com" as never); // follow-up: still changing
 
-    const handler = getActPostHandler();
-    const response = createBrowserRouteResponse();
-    const pending =
-      handler?.(
-        { params: {}, query: {}, body: { kind: "evaluate", fn: "() => 1" } },
-        response.res,
-      ) ?? Promise.resolve();
-    void pending.catch(() => {});
-    const completion = (async () => {
-      await vi.runAllTimersAsync();
-      await pending;
-    })();
-
-    await expect(completion).rejects.toThrow("Unable to verify stable post-interaction navigation");
+    await expectActionToReject({ kind: "evaluate", fn: "() => 1" });
   });
 
   it("fails closed when a probe error follows two stable reads", async () => {
@@ -336,21 +233,8 @@ describe("existing-session interaction navigation guard", () => {
       .mockRejectedValueOnce(new Error("context destroyed") as never) // location probe 3 → error
       .mockRejectedValueOnce(new Error("context destroyed") as never); // follow-up → still errored
 
-    const handler = getActPostHandler();
-    const response = createBrowserRouteResponse();
-    const pending =
-      handler?.(
-        { params: {}, query: {}, body: { kind: "evaluate", fn: "() => 1" } },
-        response.res,
-      ) ?? Promise.resolve();
-    void pending.catch(() => {});
-    const completion = (async () => {
-      await vi.runAllTimersAsync();
-      await pending;
-    })();
-
-    await expect(completion).rejects.toThrow("Unable to verify stable post-interaction navigation");
-    expect(navigationGuardMocks.assertBrowserNavigationResultAllowed).toHaveBeenCalledTimes(2);
+    await expectActionToReject({ kind: "evaluate", fn: "() => 1" });
+    expectNavigationProbeUrls(["https://example.com", "https://example.com"]);
   });
 
   it("skips the guard when no SSRF policy is configured", async () => {