jishushell 0.6.5 → 0.7.3

package/dist/services/integrations/openclaw/integration.d.ts

@@ -0,0 +1,438 @@
+/**
+ * OpenClawIntegration — the framework face of OpenClaw business logic.
+ *
+ * Legacy AppIntegration implementation retained during migration toward the
+ * model described in docs/core-app-architecture.md. The
+ * short-term goal remains: OpenClaw-specific knowledge should leave generic
+ * framework code and live behind this integration boundary.
+ *
+ * Why not a huge rewrite in a single pass?
+ *   A full physical migration of ~6500 lines of OpenClaw code out of
+ *   `instance-manager.ts` / the Nomad driver / `setup-manager.ts` is a
+ *   multi-PR undertaking. This file lands the **structural** decoupling
+ *   (contract + dispatch) today, so:
+ *
+ *     1. Every framework call site now goes through `getIntegration(integrationKind).X()`
+ *        with zero string-literal branching on "openclaw" / "hermes".
+ *     2. OpenClaw-specific imperative logic that was already contained (Nomad
+ *        task build, on-disk patches, npm update seed, pairing CLI mapping)
+ *        is physically moved into this file.
+ *     3. Larger pieces that are still entangled inside instance-manager.ts
+ *        (`saveConfig` with channel-plugin auto-install, `createInstance`
+ *        with `openclaw.json` seeding) are exposed through integration hooks
+ *        that framework code calls, and the physical code move from
+ *        instance-manager.ts into a sibling `openclaw-*.ts` file is a
+ *        straightforward follow-up PR — the `check-integration-isolation.ts`
+ *        script blocks new integration-specific code from sneaking back into the
+ *        framework layer.
+ *
+ * This is legacy AppIntegration compatibility. New app lifecycle work should
+ * follow docs/core-app-architecture.md instead of extending this as the
+ * primary app model:
+ *
+ *     1. Create `src/services/integrations/foo/integration.ts` mirroring this file.
+ *     2. Add a side-effect registration import to `src/services/integrations/index.ts`.
+ *     3. Add one line to `frontend/src/runtimes/registry.ts`.
+ *     4. Done. No `instance-manager.ts` / runtime driver / routes edits.
+ */
+import type { FastifyInstance } from "fastify";
+import { type InstallResult } from "../../setup/setup-manager.js";
+import type { AppIntegrationHooks, AppIntegrationManifest, AppIntegrationKind, BrowserConsumerActivitySummary, CapabilityProfile, ConfigDocument, InstanceConfigMeta, PairingApproveInput, AppIntegration, IntegrationConnectionSideEffectArgs, PublicProxyDescriptor, RuntimeSpec, RuntimeVersionInfo } from "../types.js";
+import type { RuntimeContribution } from "../../runtime/workload-types.js";
+export declare const OPENCLAW_DEFAULT_CONTAINER_PORT = 18789;
+export declare const OPENCLAW_PREFERRED_HOST_PORT = 18789;
+export declare const OPENCLAW_CONTROL_UI_PROXY_RE: RegExp;
+export declare function ensureOpenclawControlUiAllowedOrigin(instanceId: string, origin: string): Promise<boolean>;
+export declare function summarizeRecentOpenclawBrowserSession(instanceId: string): BrowserConsumerActivitySummary;
+export declare function isPrivateNetworkBaseUrl(baseUrl: string): boolean;
+/**
+ * Ensure `request.allowPrivateNetwork: true` is set on providers whose baseUrl
+ * targets a private/internal host (e.g. host.docker.internal). Without this,
+ * OpenClaw's SSRF guard blocks requests to the JishuShell local proxy.
+ */
+export declare function patchPrivateNetworkAllowFlag(configPath: string): void;
+/**
+ * Ensure the `llm-agent` capability advertised by openclaw-*.yaml works for
+ * every instance, including ones created before this code shipped: enable
+ * OpenClaw's OpenAI-compatible endpoints in `openclaw.json` on every start.
+ *
+ * Runs idempotently next to `patchDockerBridgeGatewayBind`. The OpenAI
+ * routes (`/v1/chat/completions`, `/v1/responses`, `/v1/models`,
+ * `/v1/embeddings`) live in openclaw's bundled server.impl and are gated
+ * behind `gateway.http.endpoints.{chatCompletions,responses}.enabled` —
+ * default false, so a fresh OpenClaw install would 404 those paths even
+ * though OpenWebUI binds it through the connections page.
+ */
+export declare function patchOpenAIEndpointsEnabled(configPath: string): void;
+/**
+ * Deep-merge a SearXNG connection into an OpenClaw config file at `configPath`.
+ *
+ * Writes both halves of the wiring required for the `web_search` tool to use
+ * the registry-resolved SearXNG instance:
+ *
+ *   plugins.entries.searxng.enabled                       = true
+ *   plugins.entries.searxng.config.webSearch.baseUrl      = baseUrl
+ *   tools.web.search.provider                             = "searxng"
+ *
+ * The provider selector is required because OpenClaw's built-in default is
+ * `"brave"`; without it the tool fails with `missing_brave_api_key` even when
+ * the searxng plugin is otherwise correctly configured (verified on Pi
+ * 2026-04-29: claw11 had the plugin block right but the selector unset).
+ *
+ * Why a partial deep-merge instead of `saveNativeConfig`: the latter is
+ * destructive — it replaces top-level keys wholesale and only preserves a
+ * hardcoded subset (`plugins.installs`, `plugins.entries` per-key, partial
+ * `channels` merge). A partial patch through it would wipe `models.providers`
+ * / `agents.defaults` / etc., bricking the instance with `No API key found
+ * for provider "openai"` on the next chat. So we read, merge, write back.
+ *
+ * No-op when the config file is absent (instance not yet started).
+ */
+export declare function applySearxngConnectionToConfig(configPath: string, baseUrl: string): void;
+/**
+ * Counterpart to `applySearxngConnectionToConfig` — invoked when the user
+ * unbinds the SEARCH slot in the Connections tab. Without this, unbinding
+ * left the plugin entry enabled with a baseUrl pointing at the now-gone
+ * searxng provider, and `tools.web.search.provider="searxng"` kept routing
+ * the agent's `web_search` tool through that dead URL on every chat.
+ *
+ * Conservative cleanup so a future re-bind (or user-customized plugin
+ * settings) survives:
+ *   - flip the searxng plugin to enabled:false (don't delete the entry —
+ *     user may have hand-tuned it and we want re-bind to re-enable cheaply)
+ *   - drop the stale `webSearch.baseUrl` so nothing reads it as still-live
+ *   - clear `tools.web.search.provider` so the runtime falls back to its
+ *     built-in default (which today errors out with `missing_brave_api_key`
+ *     — the right outcome: search was unbound, web_search shouldn't work)
+ *
+ * No-op when the config file is absent.
+ */
+export declare function clearSearxngConnectionFromConfig(configPath: string): void;
+/**
+ * Deep-merge a Browserless CDP connection into an OpenClaw config file at
+ * `configPath`. Mirrors `applySearxngConnectionToConfig` for the browser slot.
+ *
+ * Writes:
+ *   browser.profiles.browserless.cdpUrl     = cdpUrl            // ws:// or wss://
+ *   browser.profiles.browserless.attachOnly = true              // since v2026.3.2
+ *   browser.profiles.browserless.color      = "#00AA66"         // required by schema
+ *   browser.defaultProfile                  = "browserless"     // only if unset
+ *   browser.enabled                         = true              // only if unset
+ *   gateway.nodes.browser.mode              = "off"             // only if unset
+ *
+ * Why per-profile `attachOnly` and not global `browser.attachOnly`: global
+ * attachOnly forces every profile to skip launch — that breaks the user's
+ * other manually-configured profiles. Per-profile attachOnly was added in
+ * OpenClaw v2026.3.2; older versions silently ignore the extra field and
+ * fall back to attach-via-cdpUrl semantics (which `cdpUrl` triggers on its
+ * own from v2.0.0-beta5), so the schema is forward-compatible all the way
+ * back to the first remote-CDP release.
+ *
+ * Why `gateway.nodes.browser.mode = "off"`: in OpenClaw 2026.5.6 the
+ * gateway only registers the `browser.request` WS method when this config
+ * block exists. Without it, `openclaw browser …` CLI and the gateway
+ * canvas tool both fail with `unknown method: browser.request` or
+ * `node required`. Setting `mode: "off"` forces gateway-local CDP
+ * dispatch (use `cdpUrl` directly, never look for paired nodes), which
+ * matches jishushell's intent: Browserless is a service-style provider,
+ * not a node-style provider. Verified end-to-end on Pi 2 (2026-05-07):
+ * Browserless `/sessions` shows `numbConnected: 1` and `openclaw browser
+ * navigate <allowed-host>` succeeds + screenshots render correctly.
+ *
+ * `defaultProfile`, `enabled`, and `gateway.nodes.browser.mode` are all
+ * set only when absent so user-customized values survive a re-bind. The
+ * `enabled` flag is never flipped off — Browserless binding shouldn't
+ * override a user who explicitly disabled the browser tool tree.
+ *
+ * SSRF policy: on every Browserless bind, the bound CDP endpoint hostname is
+ * merged into `allowedHostnames` so OpenClaw can connect to the trusted
+ * Browserless service even when it is advertised on a private LAN address.
+ * On first bind (when the `allowedHostnames` list is empty or absent), a
+ * small set of common public-internet hosts is also pre-populated so users
+ * don't have to whitelist every popular site one by one. The public defaults
+ * are a one-time bootstrap — once the user has any entries, further binds
+ * leave those entries untouched except for refreshing the active endpoint.
+ *
+ * No-op when the config file is absent (instance not yet started).
+ */
+export declare function applyBrowserlessConnectionToConfig(configPath: string, cdpUrl: string): void;
+/**
+ * Counterpart to `applyBrowserlessConnectionToConfig` — invoked when the user
+ * unbinds the BROWSER slot in the Connections tab. Removes the
+ * jishushell-managed `browserless` profile and clears `defaultProfile` only
+ * if it still points at that profile (so user-set defaults pointing at their
+ * own profiles survive). Other profiles and `browser.enabled` are left alone.
+ *
+ * No-op when the config file is absent.
+ */
+export declare function clearBrowserlessConnectionFromConfig(configPath: string): void;
+/**
+ * Inject a guarded section into the agent's TOOLS.md telling the LLM that
+ * user files live on the local filesystem (host==container bind mount),
+ * not on some remote "drive server", and showing the concrete
+ * resolve-then-send chain for IM channels (Feishu / WeChat).
+ *
+ * Why this exists: the LLM defaults to interpreting `drive` as a remote
+ * service, then refuses to send NAS files via IM with "I can't access the
+ * cloud drive" — even when `drive_list` literally just enumerated them.
+ * Verified on pi2 2026-05-11: claw1 saw `文档/宇树G1-D...xlsx` via
+ * drive_list, then told the user to "open Feishu cloud space and forward
+ * it back" because nothing in TOOLS.md tied drive paths to filesystem
+ * paths. This patcher closes that gap by spelling it out.
+ *
+ * Idempotent: section is bracketed by HTML markers; content between them
+ * is rewritten on every call. User edits OUTSIDE the markers are kept.
+ *
+ * filesRoot is baked in so the example abs path matches the actual install
+ * — third-party users on `/home/alice/.jishushell/files/` see their own
+ * root, not pi's.
+ */
+export declare function patchToolsMdDriveHint(workspaceDir: string, filesRoot: string, mcporterCommand?: string, instanceId?: string): void;
+export declare function patchToolsMdBrowserlessHint(workspaceDir: string, mode: "install" | "remove"): void;
+/**
+ * Inject a guarded section into TOOLS.md describing the kb_search MCP
+ * tool — only when an AnythingLLM-backed knowledge base is wired into
+ * this instance. Mirrors patchToolsMdDriveHint's marker model so an
+ * uninstall / unbind can cleanly strip the section.
+ *
+ * `mode === "install"` writes the kb hint between the markers
+ * (overwriting any previous content there). `mode === "remove"`
+ * deletes the entire bracketed section, leaving the user's
+ * surrounding content intact.
+ */
+/**
+ * Resolve the `connections.KNOWLEDGE_BASE_URL` slot value (set via the
+ * Connections tab and persisted on the instance) to a concrete provider
+ * tag the kb auto-wire block knows how to materialise.
+ *
+ *   - `null`                          → user explicitly disconnected.
+ *   - `undefined`                     → no provider is bound.
+ *   - `{kind:"single", providerId}`   → use that provider, else null.
+ *   - `{kind:"many",   providers[]}`  → first known match in the user's
+ *                                       array order wins (so the UI's
+ *                                       drag-to-reorder gesture is
+ *                                       authoritative).
+ *   - unknown shape                   → unsupported binding; no provider.
+ *
+ * Step 5 boundary: this runtime hook must only interpret canonical
+ * `instance.connections`. Historical "auto AnythingLLM" behavior belongs in
+ * migration/repair, where it can be written back as an explicit binding.
+ *
+ * Exported (and not exported-default) so the helper can be unit-tested
+ * without running the whole start hook.
+ */
+export type KbProviderTag = "anythingllm" | "jishukb" | null;
+export declare function resolveKbProvider(kbBinding: unknown): KbProviderTag;
+export declare function resolveJishukbDefaultKbIdForOpenClaw(baseUrl: string, configuredKbId?: string): Promise<string>;
+/**
+ * Per-provider kb-shim residue cleanup. Wipes the shim source (replacing
+ * the bytes with a removal marker rather than `unlink`-ing — the latter
+ * would race with a concurrent `node <shim>` that already opened it) and
+ * `unlink`s the sibling `secret.json` if any. Idempotent and safe to call
+ * even if no shim was ever installed.
+ *
+ * Called by EVERY branch of the kb auto-wire block so a rebind from
+ * anythingllm ↔ jishukb (or → null) never leaves stale shim files or
+ * 0o600 secrets on disk. The "wipe by overwrite" pattern matches what
+ * the old anythingllm-only branch did before the dispatch refactor.
+ *
+ * integrationHome is the OpenClaw container's `$HOME` (the value returned by
+ * `openclawIntegration.resolveAgentHome(instanceId)`). `which` selects the
+ * provider: each gets its own `__mcp_shims__/<which>/` subtree.
+ *
+ * Exported so the security-critical secret-deletion behavior can be
+ * covered by a focused unit test without standing up the full start hook.
+ */
+export declare function wipeKbShimDir(integrationHome: string, which: "anythingllm" | "jishukb"): void;
+export declare function patchToolsMdKbHint(workspaceDir: string, mode: "install" | "remove" | "unavailable", provider?: Exclude<KbProviderTag, null>, mcporterCommand?: string, instanceId?: string, mediaInboundRoot?: string, unavailableReason?: string): void;
+export declare function patchToolsMdKbUnavailableHint(workspaceDir: string, reason?: string): void;
+/**
+ * Inject or remove the Immich MCP usage contract in TOOLS.md.
+ *
+ * Immich is registered through OpenClaw's native `mcp.servers` config, so the
+ * model receives standard tool schemas and calls them directly. This section
+ * only supplies product behavior and safety guidance; it must not teach the
+ * model to shell out through mcporter.
+ */
+export declare function patchToolsMdImmichHint(workspaceDir: string, mode: "install" | "remove", serverName?: string): void;
+/**
+ * Patch the session fence bug in OpenClaw >= 5.19 by replacing the
+ * `eventMayReachTranscriptWriters` function in the minified bundle.
+ *
+ * Idempotent: uses a marker file containing the SHA-256 of the patched
+ * file. Skips if already patched or if the pattern is not found (future
+ * fixed version or different bundle layout).
+ *
+ * Docker-only: the bug manifests through the virtiofs mount timing
+ * discrepancy between container and host — raw_exec/process modes are
+ * unaffected in practice.
+ */
+export declare function patchSessionFenceBug(openclawHome: string, instanceId: string): void;
+/**
+ * Write the container-side patch script to the openclaw-home directory so it
+ * is available inside the container via the bind mount.
+ *
+ * Called from onBeforeStart. Idempotent — only rewrites if content changed.
+ */
+export declare function writeContainerPatchScript(openclawHome: string): void;
+declare class OpenClawIntegration implements AppIntegration {
+    readonly kind: AppIntegrationKind;
+    readonly displayName = "OpenClaw";
+    readonly defaultCapabilities: CapabilityProfile;
+    readonly publicProxy: PublicProxyDescriptor;
+    readonly preferredHostPort = 18789;
+    readonly manifest: AppIntegrationManifest;
+    registerRoutes(app: FastifyInstance): Promise<void>;
+    readonly hooks: AppIntegrationHooks;
+    private prepareInitialLayout;
+    buildRuntime(instanceId: string): Promise<RuntimeSpec>;
+    getPersistedRuntimeSpec(instanceId: string): Promise<RuntimeSpec>;
+    buildRuntimeContribution(instanceId: string): Promise<RuntimeContribution>;
+    getRuntimeVersion(_instanceId: string): Promise<RuntimeVersionInfo>;
+    getConfigMeta(instanceId: string): Promise<InstanceConfigMeta>;
+    readConfig(instanceId: string): Promise<ConfigDocument>;
+    writeConfig(instanceId: string, doc: ConfigDocument): Promise<ConfigDocument>;
+    buildPairingListCommand(_instanceId: string): Promise<string[]>;
+    buildPairingApproveCommand(_instanceId: string, input: PairingApproveInput): Promise<string[]>;
+    readonly channelPluginMap: Record<string, string>;
+    /**
+     * Get the stored raw OpenClaw config (from `.openclaw/openclaw.json`
+     * or the legacy `openclaw.json`), merged with the x-jishushell
+     * metadata pulled from `instance.json`. Returns null when the instance
+     * has no persisted config yet.
+     */
+    getNativeConfig(instanceId: string): Record<string, any> | null;
+    /**
+     * Get the stored raw config WITHOUT provider key injection. Used by
+     * callers that round-trip the config back to disk (e.g. credential
+     * writers) — injecting the provider key would re-persist it to the
+     * config file, which is exactly what `saveConfig` takes pains to avoid.
+     */
+    getStoredNativeConfig(instanceId: string): Record<string, any> | null;
+    isChannelPluginInstalled(instanceId: string, channelId: string): boolean;
+    installChannelPlugin(instanceId: string, channelId: string): Promise<void>;
+    saveNativeConfig(instanceId: string, config: Record<string, any>): boolean;
+    /**
+     * Connection-apply hook: translate resolved `inject_as` env vars into
+     * OpenClaw-native plugin config and
+     * persist them into `openclaw.json`. Without this, the runtime env
+     * injected by the Nomad driver's connection env phase sits
+     * in the container unused — the OpenClaw agent reads tool config from
+     * `openclaw.json`, not from environment variables.
+     *
+     * Currently wired:
+     *   SEARCH_API_BASE_URL → plugins.entries.searxng.config.webSearch.baseUrl
+     *   SEARCH_API_BASE_URL → tools.web.search.provider = "searxng"
+     *
+     * The provider selector at `tools.web.search.provider` is required: without
+     * it the `web_search` tool defaults to Brave and fails with
+     * `missing_brave_api_key` even when the searxng plugin is fully configured.
+     *
+     * Browser / LLM wiring needs its own config-shape mapping
+     * (browser → tools.browser, llm → models.providers).
+     *
+     * The write goes through `saveNativeConfig` which preserves relevant fields
+     * from the existing canonical on-disk config, so user-managed plugin entries (e.g.
+     * openclaw-lark) are preserved. Plugin auto-enable then promotes the
+     * searxng entry into `plugins.allow` automatically on next start
+     * because we set `enabled:true` and provide config (the openclaw
+     * runtime treats the presence of `config.webSearch.baseUrl` as a
+     * "configured" signal — see `plugin-auto-enable` in the openclaw
+     * dist bundle).
+     */
+    applyConnectionEnv(instanceId: string, env: Record<string, string>): Promise<void>;
+    listConnectionSideEffectFiles(args: IntegrationConnectionSideEffectArgs): string[];
+    resolveBin(): string;
+    getSystemVersion(): string;
+    resolveAgentHome(instanceId: string): string;
+    summarizeRecentBrowserSession(instanceId: string): BrowserConsumerActivitySummary;
+    syncImmichMcpForAllInstances(): Promise<{
+        updated: string[];
+        skipped: Array<{
+            instanceId: string;
+            error: string;
+        }>;
+    }>;
+    /** Env vars OpenClaw's CLI needs when backup-manager runs it as a subprocess. */
+    buildCliEnv(instanceId: string): Record<string, string>;
+    /**
+     * Rewrite only the host-side published gateway port (canonical Step 2
+     * integration contract).
+     *
+     * Domain semantics:
+     *   - `hostPort` is Core-allocated and may be rewritten freely.
+     *   - `containerPort` is the in-container OpenClaw listener and MUST stay
+     *     stable across host-port reallocations.
+     *
+     * Missing canonical `runtime.ports[]` is a migration error for ordinary
+     * lifecycle paths; this method must not synthesize runtime facts.
+     */
+    reallocateRuntimePort(runtime: Record<string, any>, newPort: number): void;
+    readonly nomadJobPrefix = "openclaw-";
+    readonly nomadVariablePath = "openclaw/gateway";
+    resolveConfigPath(instanceId: string): string;
+    resolveLegacyConfigPath(instanceId: string): string;
+    /**
+     * Return other OpenClaw instance IDs that share this one's
+     * canonical integration-home path. Used by the start-time conflict check.
+     */
+    findInstancesSharingHome(instanceId: string): string[];
+    saveFeishuCredentials(instanceId: string, creds: {
+        appId: string;
+        appSecret: string;
+        domain: string;
+        channelKey?: string;
+    }): void;
+    saveWeixinCredentials(instanceId: string, creds: {
+        accountId: string;
+        token: string;
+        baseUrl: string;
+        userId: string;
+    }): void;
+    getWeixinAccounts(instanceId: string): Array<{
+        accountId: string;
+        userId?: string;
+        savedAt?: string;
+    }>;
+    installRuntime(opts?: {
+        version?: string;
+    }): Promise<InstallResult>;
+    /**
+     * Build / pull the OpenClaw Docker image. Blocking — useful for CLI
+     * installer and `runFullSetup()`. Non-blocking variant below is used by
+     * the REST API and the integration's own `onBeforeStart` self-heal path.
+     */
+    buildRuntimeImage(opts?: {
+        tag?: string;
+    }): Promise<InstallResult>;
+    /**
+     * Non-blocking variant of `buildRuntimeImage` — returns a task id
+     * immediately so the caller can poll SSE progress.
+     */
+    startBuildRuntimeImage(opts?: {
+        tag?: string;
+    }): InstallResult;
+    /**
+     * Return OpenClaw's readiness for spawning instances. Docker image
+     * presence is the gating factor in the default docker-mode deployment;
+     * the legacy `npm install` path is still reported as `installed` but is
+     * not required for the docker-driver stack.
+     */
+    getInstallStatus(): {
+        installed: boolean;
+        imageReady: boolean;
+        version?: string;
+        digest?: string;
+    };
+}
+/**
+ * Dissociate a cloned/imported config from its source instance's IM bindings.
+ * Physically migrated from `instance-manager.stripImBindings` so framework
+ * code no longer references OpenClaw channel concepts.
+ *
+ * Exported so `OpenClawIntegration.createInstance`'s clone path + `backup-manager`
+ * import paths can use it without depending on instance-manager.
+ */
+export declare function stripImBindings(config: Record<string, any>): void;
+export declare const openclawIntegration: OpenClawIntegration;
+export {};