jishushell 0.6.5 → 0.7.3

package/dist/services/runtime/adapters/openclaw.d.ts

@@ -1,426 +0,0 @@
-/**
- * OpenClawAdapter — the framework face of OpenClaw business logic.
- *
- * Per §32.2 / §32.8 of docs/multi-agent-runtime-generalization-plan.md, the
- * goal of this file is simple: **all OpenClaw-specific knowledge leaves the
- * framework (instance-manager / nomad-manager / routes) and lives here**.
- *
- * Why not a huge rewrite in a single pass?
- *   A full physical migration of ~6500 lines of OpenClaw code out of
- *   `instance-manager.ts` / `nomad-manager.ts` / `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 `getAdapter(agentType).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 adapter 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-adapter-isolation.ts`
- *        script (§32.2.1) will block any new code from sneaking back into
- *        the framework layer.
- *
- * The user contract for adding a THIRD agent is therefore already satisfied
- * even before the follow-up physical migration:
- *
- *     1. Create `src/services/runtime/adapters/foo.ts` mirroring this file.
- *     2. Add `import "./adapters/foo.js"` to `src/services/runtime/index.ts`.
- *     3. Add one line to `frontend/src/runtimes/registry.ts`.
- *     4. Done. No `instance-manager.ts` / `nomad-manager.ts` / routes edits.
- */
-import { type InstallResult } from "../../setup-manager.js";
-import type { AdapterHooks, AdapterManifest, AgentType, CapabilityProfile, ConfigDocument, CreateInstanceArgs, CreateInstanceContext, InstanceConfigMeta, InstancePaths, PairingApproveInput, RuntimeAdapter, RuntimeSpec, RuntimeVersionInfo } from "../types.js";
-export declare const OPENCLAW_DEFAULT_GATEWAY_PORT = 18789;
-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 is intentionally NOT touched here: `browser.ssrfPolicy`
- * (`dangerouslyAllowPrivateNetwork`, `allowedHostnames`) is a user-level
- * security decision (default deny-all is correct for an LLM-driven
- * browser); jishushell would be over-reaching to silently widen it on
- * binding. Users who want the agent to reach a specific host configure
- * the allowlist themselves.
- *
- * 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;
-/**
- * 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.
- *   - `{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).
- *   - `undefined` / unknown shape     → legacy default "anythingllm"
- *                                       so existing instances keep
- *                                       auto-on behavior.
- *
- * 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;
-/**
- * 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.
- *
- * agentHome is the OpenClaw container's `$HOME` (the value returned by
- * `openclawAdapter.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(agentHome: string, which: "anythingllm" | "jishukb"): void;
-export declare function patchToolsMdKbHint(workspaceDir: string, mode: "install" | "remove", provider?: Exclude<KbProviderTag, null>, mcporterCommand?: string, instanceId?: string, mediaInboundRoot?: 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 OpenClawAdapter implements RuntimeAdapter {
-    readonly agentType: AgentType;
-    readonly displayName = "OpenClaw";
-    readonly defaultCapabilities: CapabilityProfile;
-    readonly defaultGatewayPort = 18789;
-    readonly manifest: AdapterManifest;
-    readonly hooks: AdapterHooks;
-    /**
-     * Full OpenClaw instance bootstrap, physically migrated from the legacy
-     * `instance-manager.createInstance()` (~270 lines). Framework code now
-     * calls this uniformly via `getAdapter(agentType).createInstance(args)` —
-     * instance-manager no longer owns any OpenClaw business logic.
-     *
-     * Responsibilities:
-     *   1. openclaw_home path validation (traversal + symlink safety)
-     *   2. Gateway port allocation + runtime spec generation
-     *   3. clone_from handling (extensions/workspace/memory/sessions copy)
-     *   4. starter config seeding + default-provider API key injection
-     *   5. AppSpec overlays (config_defaults / skills)
-     *   6. Proxy bootstrap token generation via LLM proxy
-     *   7. chown to service user when running as root
-     */
-    createInstance(args: CreateInstanceArgs): Promise<Record<string, any>>;
-    createInitialLayout(ctx: CreateInstanceContext): Promise<InstancePaths>;
-    buildRuntime(instanceId: string): Promise<RuntimeSpec>;
-    buildNomadTask(instanceId: string): Promise<Record<string, any>>;
-    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[]>;
-    /**
-     * Framework delete hook — returns warnings for the caller to surface to
-     * the user. OpenClaw supports a custom `openclaw_home` pointing outside
-     * the instance directory; those directories are preserved on delete.
-     */
-    onDelete(args: {
-        instanceId: string;
-        meta: Record<string, any>;
-    }): 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 (§7 of app-interconnect-design): translate
-     * resolved `inject_as` env vars into OpenClaw-native plugin config and
-     * persist them into `openclaw.json`. Without this, the runtime env
-     * injected by `nomad-manager.injectConnectionsRuntimeEnv` (PR 8) 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 / MCP wiring lands in PR 9b — they need their own
-     * config-shape mapping (browser → tools.browser, llm → models.providers,
-     * mcp already wired via openclaw-mcporter).
-     *
-     * The write goes through `saveNativeConfig` which deep-merges with the
-     * existing 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>;
-    resolveBin(): string;
-    resolveAgentHome(instanceId: string): string;
-    /** Env vars OpenClaw's CLI needs when backup-manager runs it as a subprocess. */
-    buildCliEnv(instanceId: string): Record<string, string>;
-    /**
-     * Legacy gateway-port fallback for instances created before the
-     * RuntimeSpec.ports[] migration. OpenClaw persists its port in both
-     * `runtime.env.OPENCLAW_GATEWAY_PORT` and `runtime.args ["--port", N]`.
-     */
-    readLegacyGatewayPort(runtime: Record<string, any>): number | null;
-    /**
-     * Rewrite a persisted OpenClaw runtime spec to use a new host port.
-     * Updates `args[--port]` + `env.OPENCLAW_GATEWAY_PORT` atomically so
-     * both places stay in sync.
-     */
-    reallocateRuntimePort(runtime: Record<string, any>, newPort: number): void;
-    readonly nomadJobPrefix = "openclaw-";
-    readonly required = true;
-    readonly nomadVariablePath = "openclaw/gateway";
-    resolveConfigPath(instanceId: string): string;
-    resolveLegacyConfigPath(instanceId: string): string;
-    /**
-     * Return other OpenClaw instance IDs that share this one's
-     * `openclaw_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 adapter'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 `OpenClawAdapter.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 openclawAdapter: OpenClawAdapter;
-export {};