@mobcode/openclaw-plugin 0.1.0

package/README.md

@@ -0,0 +1,131 @@
+# MobCode OpenClaw Plugin
+
+Отдельный plugin-проект для OpenClaw, который можно ставить в уже существующий сервер OpenClaw как локальную папку.
+
+## Зачем он нужен
+
+Этот каркас заточен под мобильную интеграцию MobCode и закрывает первую архитектурную основу под такие задачи:
+
+- получить по RPC redacted snapshot runtime-конфига;
+- получать список провайдеров через MobCode static catalog;
+- получать список моделей конкретного provider через live fetch в upstream API провайдера;
+- иметь отдельное mobile-friendly хранилище сообщений по session key;
+- хранить rich artifacts и открывать их из мобильной истории;
+- маршрутизировать app-surface actions (`mobcode_open`) в активный MobCode client;
+- завести device registry и очередь push-событий;
+- подготовить базу под approvals, diff-flow и custom tools.
+
+## Что уже есть
+
+Плагин регистрирует:
+
+- gateway methods:
+  - `mobcode.capabilities`
+  - `mobcode.config.snapshot`
+  - `mobcode.providers.available`
+  - `mobcode.provider.models.list`
+  - `mobcode.messages.page`
+  - `mobcode.approvals.list`
+  - `mobcode.artifacts.get`
+  - `mobcode.artifacts.resolveBlob`
+  - `mobcode.client.register`
+  - `mobcode.client.actions.wait`
+  - `mobcode.client.actions.ack`
+ - tools:
+  - `present_artifact`
+  - `mobcode_open`
+- HTTP routes:
+  - `/plugins/mobcode/health`
+  - `/plugins/mobcode/config`
+  - `/plugins/mobcode/providers`
+  - `/plugins/mobcode/provider-models?providerId=...`
+  - `/plugins/mobcode/messages?sessionKey=...`
+  - `/plugins/mobcode/artifacts?artifactId=...`
+  - `/plugins/mobcode/devices/register`
+  - `/plugins/mobcode/client/register`
+- background service, которая:
+  - слушает transcript updates;
+  - индексирует сообщения в SQLite;
+  - делает history backfill через публичный `chat.history` и вытаскивает artifacts из tool-result history в SQLite;
+  - слушает `exec.approval.requested/resolved` через внутренний gateway approvals client;
+  - при включенном push складывает события в локальную очередь.
+- `mobcode.messages.page` отдает уже нормализованные one-bubble conversation messages с ordered timeline `text -> tool -> artifact -> text`, а не только raw transcript rows.
+
+## Что пока частично или TODO
+
+- `providers.available` сейчас отдает MobCode static provider catalog, синхронизированный с мобильным клиентом, а не настоящий OpenClaw onboarding wizard source of truth.
+- `provider.models.list` получает модели по сети для конкретного provider, используя `api.runtime.config.loadConfig()` и `api.runtime.modelAuth.resolveApiKeyForProvider(...)`, не отдавая токены в mobileapp.
+- `present_artifact` и `mobcode_open` уже зарегистрированы как plugin tools; `mobcode_open` завершает tool call после client ack или timeout.
+- real push delivery в FCM/APNs пока не сделана; есть только device registry и queue.
+- file diff flow лучше делать через интеграцию с официальным `diffs` plugin, а не изобретать свой формат.
+- mobile approvals построены поверх существующих `exec.approval.*` методов OpenClaw: plugin хранит state/history, а resolve по-прежнему идет через штатный RPC.
+- custom chart tools пока не реализованы, но под них уже есть правильная точка расширения: `registerTool`.
+- history backfill через `chat.history` portable, но ограничен 1000 последними сообщениями, потому что это hard-cap самого OpenClaw gateway method.
+
+## Установка из папки
+
+На сервере с OpenClaw:
+
+```bash
+openclaw plugins install @mobcode/openclaw-plugin
+openclaw gateway restart
+```
+
+Локальная разработка из папки по-прежнему поддерживается:
+
+```bash
+openclaw plugins install ./openclaw-mobcode-plugin
+openclaw gateway restart
+```
+
+Если хочешь линк для разработки:
+
+```bash
+openclaw plugins install -l ./openclaw-mobcode-plugin
+openclaw gateway restart
+```
+
+## Конфиг
+
+Пример plugin config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "mobcode": {
+        "enabled": true,
+        "config": {
+          "storage": {
+            "retainMessages": true,
+            "maxMessagesPerSession": 2000
+          },
+          "push": {
+            "enabled": false,
+            "provider": "none"
+          },
+          "security": {
+            "allowSecretMaterialOverGateway": false
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Следующие шаги
+
+1. Добавить `mobcode.push.dispatch` и реальную отправку в FCM/APNs/webhook relay.
+2. Подключить diff/viewer flow через официальный `diffs` plugin.
+3. Добавить `registerTool` для графиков/диаграмм поверх artifact pipeline.
+4. Заменить текущий wait/ack long-wait transport на полноценный plugin-owned event stream/push-aware channel.
+
+## Важный нюанс про portability
+
+Этот plugin больше не зависит от `openclaw/src/...` для provider/model discovery.
+
+- `mobcode.providers.available` работает на своем static catalog.
+- `mobcode.provider.models.list` работает через публичный plugin runtime (`loadConfig` + `resolveApiKeyForProvider`) и сетевой запрос к upstream provider API.
+
+Это делает plugin переносимым для обычной npm/бинарной установки OpenClaw, но означает, что provider catalog пока остается MobCode-owned, а не OpenClaw-owned source of truth.

package/index.js

@@ -0,0 +1,3 @@
+import { createMobcodePluginDefinition } from "./src/plugin-definition.js";
+
+export default createMobcodePluginDefinition();

package/openclaw.plugin.json

@@ -0,0 +1,63 @@
+{
+  "id": "mobcode",
+  "name": "MobCode",
+  "description": "MobCode mobile integration plugin for OpenClaw.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "storage": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "retainMessages": {
+            "type": "boolean",
+            "default": true
+          },
+          "maxMessagesPerSession": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 10000,
+            "default": 2000
+          }
+        }
+      },
+      "push": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false
+          },
+          "provider": {
+            "type": "string",
+            "enum": [
+              "none",
+              "webhook",
+              "fcm",
+              "apns"
+            ],
+            "default": "none"
+          },
+          "webhookUrl": {
+            "type": "string"
+          },
+          "sharedSecret": {
+            "type": "string"
+          }
+        }
+      },
+      "security": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "allowSecretMaterialOverGateway": {
+            "type": "boolean",
+            "default": false
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@mobcode/openclaw-plugin",
+  "version": "0.1.0",
+  "description": "MobCode integration plugin for OpenClaw",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.autoecommerce.ru/rootgroup/mobcode/openclaw-plugin.git"
+  },
+  "homepage": "https://gitlab.autoecommerce.ru/rootgroup/mobcode/openclaw-plugin",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    "index.js",
+    "openclaw.plugin.json",
+    "src"
+  ],
+  "keywords": [
+    "openclaw",
+    "mobcode",
+    "plugin",
+    "mobile"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ]
+  }
+}

package/src/config-utils.js

@@ -0,0 +1,148 @@
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function deepCloneJson(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function redactSecrets(value, keyName = "") {
+  if (Array.isArray(value)) {
+    return value.map((item) => redactSecrets(item));
+  }
+  if (!isObject(value)) {
+    return value;
+  }
+  const loweredKey = keyName.toLowerCase();
+  if (
+    loweredKey.includes("token") ||
+    loweredKey.includes("secret") ||
+    loweredKey.includes("apikey") ||
+    loweredKey.includes("api_key") ||
+    loweredKey.includes("password") ||
+    loweredKey.includes("privatekey") ||
+    loweredKey.includes("private_key")
+  ) {
+    return "[redacted]";
+  }
+  const result = {};
+  for (const [key, nested] of Object.entries(value)) {
+    result[key] = redactSecrets(nested, key);
+  }
+  return result;
+}
+
+function normalizeStringArray(values) {
+  return [...new Set(values.map((value) => String(value).trim()).filter(Boolean))].sort();
+}
+
+function extractConfiguredProviders(config) {
+  const providers = config?.models?.providers;
+  if (!isObject(providers)) {
+    return [];
+  }
+  return Object.entries(providers).map(([id, raw]) => ({
+    id,
+    configured: true,
+    fields: isObject(raw) ? Object.keys(raw).sort() : [],
+    hasBaseUrl: Boolean(raw?.baseUrl),
+    hasApiKey: Boolean(raw?.apiKey || raw?.api_key || raw?.token),
+  }));
+}
+
+function extractConfiguredModels(config) {
+  const models = [];
+  const defaults = config?.models?.defaults;
+  if (isObject(defaults) && defaults.provider && defaults.model) {
+    models.push({
+      source: "defaults",
+      provider: String(defaults.provider),
+      model: String(defaults.model),
+    });
+  }
+
+  const profileGroups = [
+    config?.models?.profiles,
+    config?.gateway?.profiles,
+    config?.agents?.profiles,
+  ];
+  for (const group of profileGroups) {
+    if (!isObject(group)) {
+      continue;
+    }
+    for (const [profileId, raw] of Object.entries(group)) {
+      if (!isObject(raw)) {
+        continue;
+      }
+      const provider = raw.provider ?? raw.modelProvider;
+      const model = raw.model;
+      if (!provider || !model) {
+        continue;
+      }
+      models.push({
+        source: "profile",
+        profileId,
+        provider: String(provider),
+        model: String(model),
+      });
+    }
+  }
+
+  const deduped = new Map();
+  for (const entry of models) {
+    const key = `${entry.source}:${entry.profileId ?? ""}:${entry.provider}:${entry.model}`;
+    deduped.set(key, entry);
+  }
+  return [...deduped.values()];
+}
+
+export function buildConfigSnapshot(api, options = {}) {
+  const includeSecrets =
+    options.includeSecrets === true &&
+    api?.pluginConfig?.security?.allowSecretMaterialOverGateway === true;
+  const loaded = api.runtime.config.loadConfig();
+  const rawConfig = deepCloneJson(loaded) ?? {};
+  const snapshot = includeSecrets ? rawConfig : redactSecrets(rawConfig);
+  const stateDir = api.runtime.state.resolveStateDir();
+  return {
+    generatedAt: new Date().toISOString(),
+    pluginId: api.id,
+    includeSecrets,
+    stateDir,
+    configPathHints: {
+      stateDir,
+      openclawConfigGuess: `${stateDir}/openclaw.json`,
+      runtimeSecretsGuess: `${stateDir}/runtime-secrets.json`,
+    },
+    runtimeDefaults: {
+      provider: api.runtime.agent.defaults.provider,
+      model: api.runtime.agent.defaults.model,
+    },
+    snapshot,
+  };
+}
+
+export function buildProvidersPayload(api) {
+  const config = api.runtime.config.loadConfig();
+  return {
+    generatedAt: new Date().toISOString(),
+    source: "runtime-config",
+    providers: extractConfiguredProviders(config),
+  };
+}
+
+export function buildModelsPayload(api) {
+  const config = api.runtime.config.loadConfig();
+  const configuredModels = extractConfiguredModels(config);
+  const providers = normalizeStringArray(configuredModels.map((entry) => entry.provider));
+  return {
+    generatedAt: new Date().toISOString(),
+    source: "runtime-config",
+    defaults: {
+      provider: api.runtime.agent.defaults.provider,
+      model: api.runtime.agent.defaults.model,
+    },
+    configuredProviders: providers,
+    configuredModels,
+  };
+}

package/src/feature-matrix.js

@@ -0,0 +1,49 @@
+export const MOB_CODE_FEATURE_MATRIX = {
+  configSnapshot: {
+    status: "implemented",
+    note: "Gateway method and HTTP route return a redacted runtime config snapshot and config path hints.",
+  },
+  providersList: {
+    status: "implemented",
+    note: "Provider list is derived from runtime config models/providers keys.",
+  },
+  modelsList: {
+    status: "partial",
+    note: "Current implementation returns configured/default models and heuristics from runtime config, not the full gateway catalog.",
+  },
+  fileDiffs: {
+    status: "planned",
+    note: "Best path is to integrate with the official diffs plugin or reuse its viewer/file flow.",
+  },
+  dangerousActionApprovals: {
+    status: "implemented",
+    note: "Plugin persists exec approval history/pending state for mobile reads while resolve still uses the official exec.approval.resolve RPC.",
+  },
+  pushNotifications: {
+    status: "scaffolded",
+    note: "Device registry, queue, and HTTP registration endpoints are present. Real FCM/APNs delivery is the next step.",
+  },
+  messageStorage: {
+    status: "implemented",
+    note: "Plugin indexes transcript updates into its own state for mobile-friendly reads.",
+  },
+  richArtifacts: {
+    status: "implemented",
+    note: "Plugin stores artifact documents in SQLite, exposes artifact RPC, and registers a present_artifact tool compatible with MobCode rich output flow.",
+  },
+  appSurfaceActions: {
+    status: "implemented",
+    note: "Plugin registers mobcode_open, tracks active MobCode clients, and delivers app-surface actions through wait/ack realtime-style RPC with timeout-aware tool completion.",
+  },
+  customToolsAndCharts: {
+    status: "partial",
+    note: "present_artifact and mobcode_open are implemented; chart/graph generation is the next custom-tool step.",
+  },
+};
+
+export function listFeatureMatrix() {
+  return Object.entries(MOB_CODE_FEATURE_MATRIX).map(([key, value]) => ({
+    key,
+    ...value,
+  }));
+}

package/src/gateway-methods.js

@@ -0,0 +1,180 @@
+export function registerMobcodeGatewayMethods({ store, builders, featureMatrix, api }) {
+  api.registerGatewayMethod("mobcode.capabilities", async ({ respond }) => {
+    respond(true, {
+      ok: true,
+      features: featureMatrix(),
+    });
+  });
+
+  api.registerGatewayMethod("mobcode.config.snapshot", async ({ params, respond }) => {
+    const includeSecrets = params?.includeSecrets === true;
+    respond(true, {
+      ok: true,
+      ...builders.configSnapshot({ includeSecrets }),
+    });
+  });
+
+  api.registerGatewayMethod("mobcode.providers.available", async ({ respond }) => {
+    respond(true, {
+      ok: true,
+      ...(await builders.providers()),
+    });
+  });
+
+  api.registerGatewayMethod("mobcode.provider.models.list", async ({ params, respond }) => {
+    const providerId = typeof params?.providerId === "string" ? params.providerId.trim() : "";
+    if (!providerId) {
+      respond(false, { error: "providerId required" });
+      return;
+    }
+    const payload = await builders.providerModels(providerId);
+    respond(true, {
+      ok: true,
+      ...payload,
+    });
+  });
+
+  api.registerGatewayMethod("mobcode.messages.page", async ({ params, respond }) => {
+    const sessionKey = typeof params?.sessionKey === "string" ? params.sessionKey.trim() : "";
+    if (!sessionKey) {
+      respond(false, { error: "sessionKey required" });
+      return;
+    }
+    await builders.ensureSessionMessages(sessionKey);
+    const page = await store.pageSessionMessages(sessionKey, {
+      limit: params?.limit,
+      beforeId: params?.beforeId,
+    });
+    respond(true, {
+      ok: true,
+      sessionKey: page.sessionKey,
+      messages: page.items,
+      hasMore: page.hasMore,
+      nextBeforeId: page.nextBeforeId,
+      total: page.total,
+    });
+  });
+
+  api.registerGatewayMethod("mobcode.approvals.list", async ({ params, respond }) => {
+    const approvals = await store.listApprovals({
+      sessionKey:
+        typeof params?.sessionKey === "string" ? params.sessionKey.trim() : undefined,
+      status: typeof params?.status === "string" ? params.status.trim() : undefined,
+      limit: params?.limit,
+    });
+    respond(true, {
+      ok: true,
+      approvals,
+    });
+  });
+
+  api.registerGatewayMethod("mobcode.artifacts.get", async ({ params, respond }) => {
+    const artifactId = typeof params?.artifactId === "string" ? params.artifactId.trim() : "";
+    if (!artifactId) {
+      respond(false, { error: "artifactId required" });
+      return;
+    }
+    const artifact = await store.readArtifactById(artifactId);
+    if (!artifact?.document) {
+      respond(false, { error: "artifact not found" });
+      return;
+    }
+    respond(true, {
+      ok: true,
+      artifactId: artifact.artifactId,
+      document: artifact.document,
+      sessionKey: artifact.sessionKey,
+      runId: artifact.runId,
+      kind: artifact.kind,
+      title: artifact.title,
+      summary: artifact.summary,
+    });
+  });
+
+  api.registerGatewayMethod("mobcode.artifacts.resolveBlob", async ({ params, respond }) => {
+    const blobId = typeof params?.blobId === "string" ? params.blobId.trim() : "";
+    if (!blobId) {
+      respond(false, { error: "blobId required" });
+      return;
+    }
+    const path = await store.resolveArtifactBlobPath(blobId);
+    if (!path) {
+      respond(false, { error: "blob not found" });
+      return;
+    }
+    respond(true, {
+      ok: true,
+      blobId,
+      path,
+    });
+  });
+
+  api.registerGatewayMethod("mobcode.client.register", async ({ params, respond }) => {
+    const clientId = typeof params?.clientId === "string" ? params.clientId.trim() : "";
+    if (!clientId) {
+      respond(false, { error: "clientId required" });
+      return;
+    }
+    const result = await store.registerClientSession({
+      clientId,
+      sessionKey: typeof params?.sessionKey === "string" ? params.sessionKey.trim() : "",
+      platform: typeof params?.platform === "string" ? params.platform.trim() : "",
+      appVersion: typeof params?.appVersion === "string" ? params.appVersion.trim() : "",
+      capabilities: params?.capabilities && typeof params.capabilities === "object"
+        ? params.capabilities
+        : {},
+    });
+    respond(true, {
+      ok: true,
+      ...result,
+    });
+  });
+
+  api.registerGatewayMethod("mobcode.client.actions.poll", async ({ params, respond }) => {
+    const clientId = typeof params?.clientId === "string" ? params.clientId.trim() : "";
+    if (!clientId) {
+      respond(false, { error: "clientId required" });
+      return;
+    }
+    const actions = await store.pollClientActions(clientId, {
+      limit: params?.limit,
+    });
+    respond(true, {
+      ok: true,
+      actions,
+    });
+  });
+
+  api.registerGatewayMethod("mobcode.client.actions.wait", async ({ params, respond }) => {
+    const clientId = typeof params?.clientId === "string" ? params.clientId.trim() : "";
+    if (!clientId) {
+      respond(false, { error: "clientId required" });
+      return;
+    }
+    const action = await store.waitForClientAction(clientId, {
+      timeoutMs: params?.timeoutMs,
+    });
+    respond(true, {
+      ok: true,
+      action,
+    });
+  });
+
+  api.registerGatewayMethod("mobcode.client.actions.ack", async ({ params, respond }) => {
+    const clientId = typeof params?.clientId === "string" ? params.clientId.trim() : "";
+    const actionId = typeof params?.actionId === "string" ? params.actionId.trim() : "";
+    const status = typeof params?.status === "string" ? params.status.trim() : "";
+    if (!clientId || !actionId || !status) {
+      respond(false, { error: "clientId, actionId, and status are required" });
+      return;
+    }
+    respond(true, {
+      ...(await store.ackClientAction({
+        clientId,
+        actionId,
+        status,
+        errorText: typeof params?.errorText === "string" ? params.errorText.trim() : "",
+      })),
+    });
+  });
+}