jishushell 0.6.5 → 0.7.3

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

@@ -0,0 +1,194 @@
+/**
+ * HermesIntegration — first non-OpenClaw runtime integration.
+ *
+ * Legacy AppIntegration implementation retained during migration toward the
+ * model described in docs/core-app-architecture.md.
+ *
+ * Current scope:
+ *   - Only create / buildRuntime / getRuntimeVersion are wired up.
+ *   - Baseline image mode only. Overlay upgrade CLI is deferred.
+ *   - Assumes the Hermes integration runtime record has been populated in
+ *     core.json.runtime_catalog.hermes: defaultImage (+ optional
+ *     defaultImageDigest), resources, homeDirName.
+ */
+import { type InstallResult } from "../../setup/setup-manager.js";
+import type { AppIntegrationHooks, AppIntegrationManifest, ConfigDocument, InstancePaths, AppIntegration, IntegrationConnectionSideEffectArgs, RuntimeSpec, RuntimeVersionInfo, CapabilityProfile, InstanceConfigMeta, PairingApproveInput } from "../types.js";
+import type { RuntimeContribution } from "../../runtime/workload-types.js";
+export declare const HERMES_PREFERRED_HOST_PORT = 8642;
+/**
+ * One-shot startup migration for Hermes installs whose
+ * catalog still stores `:latest` / `:slim`. Silent no-op when the catalog
+ * already holds a pinned tag, when docker is unreachable, or when the
+ * local image lacks the expected LABEL. Called from server.ts onReady.
+ */
+export declare function migrateHermesImageTagIfNeeded(): void;
+/**
+ * Resolve the hermes instance filesystem layout. Agent-home lives inside the
+ * per-instance directory and is bind-mounted to /opt/data inside the container.
+ */
+export declare function resolveHermesPaths(instanceId: string): InstancePaths;
+declare class HermesIntegration implements AppIntegration {
+    readonly kind: "hermes";
+    readonly displayName = "Hermes Agent";
+    readonly defaultCapabilities: CapabilityProfile;
+    readonly preferredHostPort = 8642;
+    readonly manifest: AppIntegrationManifest;
+    readonly hooks: AppIntegrationHooks;
+    private prepareInitialLayout;
+    buildRuntime(instanceId: string): Promise<RuntimeSpec>;
+    getPersistedRuntimeSpec(instanceId: string): Promise<RuntimeSpec>;
+    buildRuntimeContribution(instanceId: string): Promise<RuntimeContribution>;
+    /**
+     * Hermes has no `openclaw.json` — it stores upstream metadata directly
+     * on instance.json under `x-jishushell`. Return a synthetic stub
+     * containing just that block so the LLM proxy's
+     * `deriveUpstreamConfig()` finds what it needs.
+     */
+    getNativeConfig(instanceId: string): Record<string, any> | null;
+    getStoredNativeConfig(instanceId: string): Record<string, any> | null;
+    /**
+     * Persist the `x-jishushell` meta block to instance.json. Hermes's user-
+     * facing config lives in yaml+env (editable via `writeConfig`), so this
+     * hook is scoped to the meta block only — any other keys in the payload
+     * are ignored intentionally.
+     *
+     * Called by `llm-proxy.saveInstanceConfig` when the editor saves a
+     * per-instance provider override. By implementing the same
+     * `saveNativeConfig(instanceId, {x-jishushell})` contract OpenClaw uses,
+     * Hermes piggy-backs on the shared API key encryption + rollback flow.
+     */
+    saveNativeConfig(instanceId: string, config: Record<string, any>): boolean;
+    /**
+     * Connection-apply hook: translate resolved bindings into Hermes-native
+     * config.yaml updates.
+     *
+     * Hermes' web tool only supports Firecrawl/Tavily/Exa/Parallel as direct
+     * search backends — it does NOT recognize SearXNG natively. We expose
+     * SearXNG (and any other MCP-shaped capability) to the agent via the
+     * jishushell MCP firewall (see `runtime/mcp-shims/firewall.ts`).
+     *
+     * The firewall replaces the upstream package's `tools/list` description
+     * with the canonical wording declared in app yaml's
+     * `provides[].tool_schema` — preventing prompt-injection like the
+     * "news / recent events" + `time_range` slots of upstream `mcp-searxng`,
+     * which was rewriting Chinese queries into English and hallucinating
+     * dates on MiniMax-class models.
+     *
+     * For each `SEARCH_API_BASE_URL` (or future MCP-shaped slot):
+     *   1. Find the producing capability entry in the registry.
+     *   2. If it carries `toolSchema`, drop firewall + config.json into
+     *      agent-home and write `mcp_servers.<cap_id>` pointing at it.
+     *   3. If it doesn't (legacy yaml without §17 fields), fall back to
+     *      the PR 7 in-tree searxng-shim — kept for one release cycle as
+     *      backstop while community apps migrate.
+     *
+     * Other env (OPENAI_API_BASE_URL etc.) is a no-op here; the framework
+     * still injects them through the Nomad driver's runtime env phase
+     * and Hermes picks them up natively.
+     */
+    applyConnectionEnv(instanceId: string, env: Record<string, string>): Promise<void>;
+    listConnectionSideEffectFiles(args: IntegrationConnectionSideEffectArgs): string[];
+    getRuntimeVersion(instanceId: string): Promise<RuntimeVersionInfo>;
+    getConfigMeta(instanceId: string): Promise<InstanceConfigMeta>;
+    readConfig(instanceId: string): Promise<ConfigDocument>;
+    writeConfig(instanceId: string, doc: ConfigDocument): Promise<ConfigDocument>;
+    /**
+     * Persist Feishu/Lark OAuth credentials returned by the device-flow
+     * endpoints. The HTTP route belongs to the OpenClaw integration surface, but
+     * persistence dispatches through the consumer integration here because Hermes
+     * owns its private config/env layout.
+     *
+     * Hermes reads platform config from two places on every gateway start:
+     *   - `config.yaml` → `platforms.feishu.enabled` + `platforms.feishu.extra.*`
+     *   - `.env`         → `FEISHU_APP_ID`, `FEISHU_APP_SECRET`
+     *
+     * We write into BOTH. The YAML holds structural config (enabled flag,
+     * connection mode, domain) and references the secret env vars via
+     * `${...}` interpolation. That way the YAML can be backed up / shared
+     * without leaking credentials, and the real secrets live next to the
+     * .env the user already edits.
+     */
+    saveFeishuCredentials(instanceId: string, creds: {
+        appId: string;
+        appSecret: string;
+        domain: string;
+        channelKey?: string;
+    }): void;
+    /**
+     * Persist WeChat (personal-account) credentials returned by iLink Bot API's QR
+     * login flow. Called from the shared `/api/instances/:id/weixin/login`
+     * handler via `instance-manager.saveWeixinCredentials` → integration dispatch.
+     *
+     * Upstream Hermes's `WeixinAdapter.__init__` scans
+     * `$HERMES_HOME/weixin/accounts/*.json` at startup and auto-connects every
+     * account file it finds, so the handshake we persist here is everything
+     * the runtime needs to come online after an instance restart. The JSON
+     * shape is pinned to upstream's `save_weixin_account` helper:
+     * `{token, base_url, user_id, saved_at}` with mode 0600.
+     *
+     * We also flip `platforms.weixin.enabled: true` in the instance's
+     * config.yaml so the gateway actually tries to connect the integration on
+     * next start (without it, hermes ignores the weixin folder entirely).
+     */
+    saveWeixinCredentials(instanceId: string, creds: {
+        accountId: string;
+        token: string;
+        baseUrl: string;
+        userId: string;
+    }): void;
+    /**
+     * List connected WeChat accounts for an instance. Backs the panel UI's
+     * "Connected Accounts" section in WeixinLoginPanel. Tolerates a missing
+     * directory (returns empty) and skips sidecar files the runtime writes
+     * alongside account records (sync buffers + context-token caches).
+     */
+    getWeixinAccounts(instanceId: string): Array<{
+        accountId: string;
+        userId?: string;
+        savedAt?: string;
+    }>;
+    /**
+     * Rewrite only the host-side published gateway port.
+     *
+     * Hermes keeps listening on a fixed `HERMES_CONTAINER_PORT` inside the
+     * container regardless of how Core publishes it; reallocation only
+     * touches `hostPort`. Missing canonical `runtime.ports[]` is a migration
+     * error for ordinary lifecycle paths.
+     */
+    reallocateRuntimePort(runtime: Record<string, any>, newPort: number): void;
+    readonly nomadJobPrefix = "hermes-";
+    normalizeCoreConfigOnStartup(): void;
+    readonly inlineChatDescriptor: {
+        readonly apiKeyEnvVar: "API_SERVER_KEY";
+        readonly endpointPath: "/v1/chat/completions";
+    };
+    buildPairingListCommand(_instanceId: string): Promise<string[]>;
+    buildPairingApproveCommand(_instanceId: string, input: PairingApproveInput): Promise<string[]>;
+    installRuntime(_opts?: Record<string, any>): Promise<InstallResult>;
+    /**
+     * Non-blocking variant — returns a task id immediately and runs the
+     * install in the background. Matches OpenClaw's startBuildRuntimeImage.
+     */
+    startInstallRuntime(_opts?: Record<string, any>): InstallResult;
+    /**
+     * Shared helper that pulls (or builds) the Hermes runtime image and
+     * finalises the integration runtime record. Mirrors OpenClaw's
+     * `pullOrBuildOpenclawImageWithTask` so both runtimes expose the same
+     * install UX (local → pull → fallback build → digest pin).
+     */
+    private prepareHermesWithTask;
+    /**
+     * Hermes readiness: the image must retain an official RepoDigest from
+     * ghcr.io/x-aijishu/hermes-runtime. This accepts images pulled directly
+     * from our registry (and docker save/load copies that preserve RepoDigests)
+     * while rejecting arbitrary local retags that only look like Hermes runtime.
+     */
+    getInstallStatus(): {
+        installed: boolean;
+        imageReady: boolean;
+        version?: string;
+        digest?: string;
+    };
+}
+export declare const hermesIntegration: HermesIntegration;
+export {};