@mobcode/openclaw-plugin 0.1.0

package/src/http-routes.js

@@ -0,0 +1,159 @@
+function jsonResponse(payload, status = 200) {
+  return new Response(JSON.stringify(payload, null, 2), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+    },
+  });
+}
+
+async function readJsonBody(request) {
+  try {
+    return await request.json();
+  } catch {
+    return null;
+  }
+}
+
+export function registerMobcodeHttpRoutes({ api, store, builders }) {
+  api.registerHttpRoute({
+    path: "/plugins/mobcode/health",
+    auth: "plugin",
+    match: "exact",
+    handler: async () =>
+      jsonResponse({
+        ok: true,
+        pluginId: api.id,
+        generatedAt: new Date().toISOString(),
+      }),
+  });
+
+  api.registerHttpRoute({
+    path: "/plugins/mobcode/config",
+    auth: "plugin",
+    match: "exact",
+    handler: async (ctx) => {
+      const includeSecrets = ctx.url.searchParams.get("includeSecrets") === "1";
+      return jsonResponse(builders.configSnapshot({ includeSecrets }));
+    },
+  });
+
+  api.registerHttpRoute({
+    path: "/plugins/mobcode/providers",
+    auth: "plugin",
+    match: "exact",
+    handler: async () => jsonResponse(await builders.providers()),
+  });
+
+  api.registerHttpRoute({
+    path: "/plugins/mobcode/provider-models",
+    auth: "plugin",
+    match: "exact",
+    handler: async (ctx) => {
+      const providerId = ctx.url.searchParams.get("providerId")?.trim();
+      if (!providerId) {
+        return jsonResponse({ error: "providerId query param required" }, 400);
+      }
+      return jsonResponse(await builders.providerModels(providerId));
+    },
+  });
+
+  api.registerHttpRoute({
+    path: "/plugins/mobcode/messages",
+    auth: "plugin",
+    match: "exact",
+    handler: async (ctx) => {
+      const sessionKey = ctx.url.searchParams.get("sessionKey")?.trim();
+      if (!sessionKey) {
+        return jsonResponse({ error: "sessionKey query param required" }, 400);
+      }
+      await builders.ensureSessionMessages(sessionKey);
+      return jsonResponse(
+        await store.pageSessionMessages(sessionKey, {
+          limit: Number.parseInt(ctx.url.searchParams.get("limit") ?? "100", 10),
+        }),
+      );
+    },
+  });
+
+  api.registerHttpRoute({
+    path: "/plugins/mobcode/approvals",
+    auth: "plugin",
+    match: "exact",
+    handler: async (ctx) =>
+      jsonResponse({
+        approvals: await store.listApprovals({
+          sessionKey: ctx.url.searchParams.get("sessionKey")?.trim(),
+          status: ctx.url.searchParams.get("status")?.trim() ?? "pending",
+          limit: Number.parseInt(ctx.url.searchParams.get("limit") ?? "100", 10),
+        }),
+      }),
+  });
+
+  api.registerHttpRoute({
+    path: "/plugins/mobcode/artifacts",
+    auth: "plugin",
+    match: "exact",
+    handler: async (ctx) => {
+      const artifactId = ctx.url.searchParams.get("artifactId")?.trim();
+      if (!artifactId) {
+        return jsonResponse({ error: "artifactId query param required" }, 400);
+      }
+      const artifact = await store.readArtifactById(artifactId);
+      if (!artifact?.document) {
+        return jsonResponse({ error: "artifact not found" }, 404);
+      }
+      return jsonResponse({
+        ok: true,
+        artifactId: artifact.artifactId,
+        document: artifact.document,
+      });
+    },
+  });
+
+  api.registerHttpRoute({
+    path: "/plugins/mobcode/devices/register",
+    auth: "plugin",
+    match: "exact",
+    handler: async (ctx) => {
+      const body = await readJsonBody(ctx.request);
+      const token = typeof body?.token === "string" ? body.token.trim() : "";
+      const platform = typeof body?.platform === "string" ? body.platform.trim() : "";
+      if (!token || !platform) {
+        return jsonResponse({ error: "platform and token are required" }, 400);
+      }
+      const result = await store.upsertDevice({
+        platform,
+        token,
+        deviceId: typeof body?.deviceId === "string" ? body.deviceId.trim() : "",
+        appVersion: typeof body?.appVersion === "string" ? body.appVersion.trim() : "",
+      });
+      return jsonResponse({ ok: true, count: result.devices.length });
+    },
+  });
+
+  api.registerHttpRoute({
+    path: "/plugins/mobcode/client/register",
+    auth: "plugin",
+    match: "exact",
+    handler: async (ctx) => {
+      const body = await readJsonBody(ctx.request);
+      try {
+        return jsonResponse({
+          ok: true,
+          ...(await store.registerClientSession({
+            clientId: typeof body?.clientId === "string" ? body.clientId.trim() : "",
+            sessionKey: typeof body?.sessionKey === "string" ? body.sessionKey.trim() : "",
+            platform: typeof body?.platform === "string" ? body.platform.trim() : "",
+            appVersion: typeof body?.appVersion === "string" ? body.appVersion.trim() : "",
+            capabilities: body?.capabilities && typeof body.capabilities === "object"
+              ? body.capabilities
+              : {},
+          })),
+        });
+      } catch (error) {
+        return jsonResponse({ error: error instanceof Error ? error.message : "invalid body" }, 400);
+      }
+    },
+  });
+}

package/src/openclaw-gateway-runtime.js

@@ -0,0 +1,85 @@
+async function tryImport(modulePath) {
+  try {
+    return await import(modulePath);
+  } catch {
+    return null;
+  }
+}
+
+async function loadGatewayRuntime() {
+  return (
+    (await tryImport("openclaw/plugin-sdk/gateway-runtime")) ??
+    (await tryImport("../../openclaw/src/plugin-sdk/gateway-runtime.ts")) ??
+    (await tryImport("../../openclaw/src/plugin-sdk/gateway-runtime.js")) ??
+    (await tryImport("../openclaw/src/plugin-sdk/gateway-runtime.js"))
+  );
+}
+
+export async function tryCreateOperatorApprovalsGatewayClient(params) {
+  const runtime = await loadGatewayRuntime();
+  if (!runtime?.createOperatorApprovalsGatewayClient) {
+    return null;
+  }
+  return runtime.createOperatorApprovalsGatewayClient(params);
+}
+
+export async function requestThroughOperatorApprovalsGateway(params) {
+  let resolveHello;
+  let rejectHello;
+  let helloSettled = false;
+  const helloPromise = new Promise((resolve, reject) => {
+    resolveHello = resolve;
+    rejectHello = reject;
+  });
+  const timeoutId = setTimeout(() => {
+    if (helloSettled) {
+      return;
+    }
+    helloSettled = true;
+    rejectHello(new Error("gateway hello timeout"));
+  }, 5000);
+  timeoutId.unref?.();
+
+  const client = await tryCreateOperatorApprovalsGatewayClient({
+    config: params.config,
+    gatewayUrl: params.gatewayUrl,
+    clientDisplayName: params.clientDisplayName ?? "MobCode Gateway RPC",
+    onHelloOk: () => {
+      if (helloSettled) {
+        return;
+      }
+      helloSettled = true;
+      clearTimeout(timeoutId);
+      resolveHello(true);
+    },
+    onConnectError: (err) => {
+      params.onConnectError?.(err);
+      if (helloSettled) {
+        return;
+      }
+      helloSettled = true;
+      clearTimeout(timeoutId);
+      rejectHello(err);
+    },
+    onClose: (_code, reason) => {
+      if (helloSettled) {
+        return;
+      }
+      helloSettled = true;
+      clearTimeout(timeoutId);
+      rejectHello(new Error(reason || "gateway closed before hello"));
+    },
+  });
+  if (!client) {
+    clearTimeout(timeoutId);
+    throw new Error("operator approvals gateway runtime unavailable");
+  }
+
+  client.start();
+  try {
+    await helloPromise;
+    return await client.request(params.method, params.requestParams);
+  } finally {
+    client.stop();
+  }
+}

package/src/openclaw-introspection.js

@@ -0,0 +1,10 @@
+import { buildStaticProvidersPayload } from "./provider-catalog.js";
+import { buildProviderModelsPayloadFromInternet } from "./provider-model-fetch.js";
+
+export async function tryBuildAvailableProvidersPayload() {
+  return buildStaticProvidersPayload();
+}
+
+export async function tryBuildProviderModelsPayload(api, providerId) {
+  return await buildProviderModelsPayloadFromInternet(api, providerId);
+}

package/src/openclaw-session-reader.js

@@ -0,0 +1,75 @@
+import { requestThroughOperatorApprovalsGateway } from "./openclaw-gateway-runtime.js";
+
+async function tryImport(modulePath) {
+  try {
+    return await import(modulePath);
+  } catch {
+    return null;
+  }
+}
+
+async function loadSessionUtilsRuntime() {
+  return (
+    (await tryImport("../../openclaw/src/gateway/session-utils.js")) ??
+    (await tryImport("../openclaw/src/gateway/session-utils.js"))
+  );
+}
+
+async function readSessionTranscriptMessagesFromInternals(sessionKey) {
+  const runtime = await loadSessionUtilsRuntime();
+  if (!runtime?.loadSessionEntry || !runtime?.readSessionMessages) {
+    return [];
+  }
+
+  const normalizedSessionKey = String(sessionKey ?? "").trim();
+  if (!normalizedSessionKey) {
+    return [];
+  }
+
+  const loaded = runtime.loadSessionEntry(normalizedSessionKey);
+  const entry = loaded?.entry;
+  const storePath = loaded?.storePath;
+  const sessionId =
+    typeof entry?.sessionId === "string" && entry.sessionId.trim()
+      ? entry.sessionId.trim()
+      : "";
+  if (!sessionId) {
+    return [];
+  }
+
+  const rawMessages = runtime.readSessionMessages(sessionId, storePath, entry?.sessionFile);
+  return Array.isArray(rawMessages) ? rawMessages : [];
+}
+
+async function readSessionMessagesThroughChatHistory(config, sessionKey) {
+  const normalizedSessionKey = String(sessionKey ?? "").trim();
+  if (!normalizedSessionKey) {
+    return [];
+  }
+  const payload = await requestThroughOperatorApprovalsGateway({
+    config,
+    method: "chat.history",
+    requestParams: {
+      sessionKey: normalizedSessionKey,
+      limit: 1000,
+    },
+    clientDisplayName: "MobCode History Backfill",
+  });
+  const messages = payload?.messages;
+  return Array.isArray(messages) ? messages : [];
+}
+
+export async function readSessionTranscriptMessages(config, sessionKey) {
+  try {
+    const gatewayMessages = await readSessionMessagesThroughChatHistory(
+      config,
+      sessionKey,
+    );
+    if (gatewayMessages.length > 0) {
+      return gatewayMessages;
+    }
+  } catch {
+    // Fall back to adjacent-source runtime imports for development checkouts.
+  }
+  return readSessionTranscriptMessagesFromInternals(sessionKey);
+}

package/src/plugin-definition.js

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { listFeatureMatrix } from "./feature-matrix.js";
+import {
+  buildConfigSnapshot,
+} from "./config-utils.js";
+import { registerMobcodeGatewayMethods } from "./gateway-methods.js";
+import { registerMobcodeHttpRoutes } from "./http-routes.js";
+import {
+  tryBuildAvailableProvidersPayload,
+  tryBuildProviderModelsPayload,
+} from "./openclaw-introspection.js";
+import { readSessionTranscriptMessages } from "./openclaw-session-reader.js";
+import { registerMobcodeRuntimeObservers } from "./runtime-events.js";
+import { MobcodeStateStore } from "./state-store.js";
+import { registerMobcodeTools } from "./plugin-tools.js";
+
+export function createMobcodePluginDefinition() {
+  return {
+    id: "mobcode",
+    name: "MobCode",
+    description: "MobCode mobile integration plugin for OpenClaw.",
+    register(api) {
+      const pluginConfig = api.pluginConfig ?? {};
+      const stateDir = api.runtime.state.resolveStateDir();
+      const store = new MobcodeStateStore({
+        rootDir: path.join(stateDir, "plugins", "mobcode"),
+      });
+
+      const builders = {
+        configSnapshot: (options) => buildConfigSnapshot(api, options),
+        providers: async () => await tryBuildAvailableProvidersPayload(api),
+        providerModels: async (providerId) =>
+          await tryBuildProviderModelsPayload(api, providerId),
+        ensureSessionMessages: async (sessionKey) => {
+          await store.ensureSessionIndexed(sessionKey, async () =>
+            readSessionTranscriptMessages(api.runtime.config.loadConfig(), sessionKey),
+          );
+        },
+      };
+
+      registerMobcodeGatewayMethods({
+        api,
+        store,
+        builders,
+        featureMatrix: listFeatureMatrix,
+      });
+      registerMobcodeHttpRoutes({
+        api,
+        store,
+        builders,
+      });
+      registerMobcodeRuntimeObservers({
+        api,
+        store,
+        pluginConfig,
+      });
+      registerMobcodeTools({
+        api,
+        store,
+      });
+    },
+  };
+}

package/src/plugin-tools.js

@@ -0,0 +1,300 @@
+function buildJsonTextContent(payload) {
+  return JSON.stringify(payload, null, 2);
+}
+
+function normalizeString(value) {
+  return String(value ?? "").trim();
+}
+
+function normalizeOpenParams(raw) {
+  if (raw == null) {
+    return {};
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("params must be an object when provided.");
+  }
+  return Object.fromEntries(
+    Object.entries(raw).map(([key, value]) => [String(key), value]),
+  );
+}
+
+function readOptionalInt(value, label) {
+  if (value == null) return null;
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return Math.trunc(value);
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number.parseInt(value.trim(), 10);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+  throw new Error(`${label} must be an integer when provided.`);
+}
+
+function assertAllowedKeys(target, params, allowedKeys) {
+  const invalidKeys = Object.keys(params).filter((key) => !allowedKeys.includes(key));
+  if (invalidKeys.length === 0) return;
+  throw new Error(
+    `target=${target} does not support params: ${invalidKeys.join(", ")}. Allowed params: ${allowedKeys.join(", ")}.`,
+  );
+}
+
+function validateMobcodeOpenArgs(rawArgs) {
+  const target = normalizeString(rawArgs?.target).toLowerCase();
+  if (!target) {
+    throw new Error(
+      "target is required. Supported targets: browser_tab, file, terminal, docker, kubernetes, local_agent, openclaw.",
+    );
+  }
+  const allowedTargets = [
+    "browser_tab",
+    "file",
+    "terminal",
+    "docker",
+    "kubernetes",
+    "local_agent",
+    "openclaw",
+  ];
+  if (!allowedTargets.includes(target)) {
+    throw new Error(
+      `Unsupported target "${target}". Supported targets: ${allowedTargets.join(", ")}.`,
+    );
+  }
+  const params = normalizeOpenParams(rawArgs?.params);
+  switch (target) {
+    case "browser_tab": {
+      assertAllowedKeys(target, params, ["url"]);
+      const url = normalizeString(params.url);
+      if (!url) {
+        throw new Error("target=browser_tab requires params.url as a non-empty string.");
+      }
+      break;
+    }
+    case "file": {
+      assertAllowedKeys(target, params, ["path", "start_line", "end_line"]);
+      const path = normalizeString(params.path);
+      if (!path) {
+        throw new Error("target=file requires params.path as a non-empty string.");
+      }
+      readOptionalInt(params.start_line, "target=file expects params.start_line");
+      readOptionalInt(params.end_line, "target=file expects params.end_line");
+      break;
+    }
+    case "terminal":
+      assertAllowedKeys(target, params, ["command"]);
+      break;
+    case "docker":
+    case "kubernetes":
+    case "local_agent":
+    case "openclaw":
+      assertAllowedKeys(target, params, ["section"]);
+      break;
+  }
+  return { target, params };
+}
+
+function normalizeArtifactDocument(rawArtifact) {
+  if (!rawArtifact || typeof rawArtifact !== "object" || Array.isArray(rawArtifact)) {
+    throw new Error("artifact object is required");
+  }
+  const artifactId = normalizeString(rawArtifact.artifactId ?? rawArtifact.artifact_id);
+  const kind = normalizeString(rawArtifact.kind);
+  const title = normalizeString(rawArtifact.title);
+  if (!artifactId) {
+    throw new Error("artifact.artifactId is required");
+  }
+  if (!kind) {
+    throw new Error("artifact.kind is required");
+  }
+  if (!title) {
+    throw new Error("artifact.title is required");
+  }
+  const initialScreenId = normalizeString(
+    rawArtifact.initialScreenId ?? rawArtifact.initial_screen_id ?? "main",
+  );
+  const screens = Array.isArray(rawArtifact.screens) ? rawArtifact.screens : [];
+  const actions = Array.isArray(rawArtifact.actions) ? rawArtifact.actions : [];
+  const media = Array.isArray(rawArtifact.media) ? rawArtifact.media : [];
+  return {
+    schemaVersion: Number(rawArtifact.schemaVersion ?? rawArtifact.schema_version ?? 1) || 1,
+    artifactId,
+    kind,
+    title,
+    ...(normalizeString(rawArtifact.summary)
+      ? { summary: normalizeString(rawArtifact.summary) }
+      : {}),
+    initialScreenId: initialScreenId || "main",
+    screens,
+    actions,
+    localStateSchema:
+      rawArtifact.localStateSchema && typeof rawArtifact.localStateSchema === "object"
+        ? rawArtifact.localStateSchema
+        : rawArtifact.local_state_schema &&
+            typeof rawArtifact.local_state_schema === "object"
+          ? rawArtifact.local_state_schema
+          : {},
+    ...(rawArtifact.preview && typeof rawArtifact.preview === "object"
+      ? { preview: rawArtifact.preview }
+      : {}),
+    media,
+    ...(rawArtifact.metadata && typeof rawArtifact.metadata === "object"
+      ? { metadata: rawArtifact.metadata }
+      : {}),
+  };
+}
+
+function buildArtifactRefBlock(document) {
+  return {
+    type: "artifact_ref",
+    artifactId: document.artifactId,
+    kind: document.kind,
+    title: document.title,
+    ...(normalizeString(document.summary) ? { summary: document.summary } : {}),
+    document,
+  };
+}
+
+export function registerMobcodeTools({ api, store }) {
+  api.registerTool(
+    (context) => ({
+      name: "present_artifact",
+      description:
+        "Publish or update a strict, runtime-validated rich artifact in chat. Use the same artifact document contract as MobCode local agent.",
+      parameters: {
+        type: "object",
+        properties: {
+          item_id: { type: "string" },
+          op: {
+            type: "string",
+            enum: ["start", "patch", "done"],
+          },
+          artifact: {
+            type: "object",
+            description: "Artifact document payload.",
+          },
+        },
+        required: ["artifact"],
+        additionalProperties: false,
+      },
+      execute: async (_toolCallId, rawArgs) => {
+        const args = rawArgs && typeof rawArgs === "object" ? rawArgs : {};
+        const sessionKey = normalizeString(context?.sessionKey);
+        if (!sessionKey) {
+          throw new Error("sessionKey is required for present_artifact.");
+        }
+        const document = normalizeArtifactDocument(args.artifact);
+        const saved = await store.upsertArtifact({
+          sessionKey,
+          runId: normalizeString(args._runId),
+          document,
+        });
+        const refBlock = buildArtifactRefBlock(document);
+        const itemId = normalizeString(args.item_id) || document.artifactId;
+        const op = normalizeString(args.op || "done").toLowerCase() || "done";
+        const payload = {
+          ok: true,
+          artifact: saved.document,
+          content_blocks: [refBlock],
+          action: {
+            type: "artifact",
+            op,
+            item_id: itemId,
+            block: refBlock,
+          },
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: buildJsonTextContent(payload),
+            },
+          ],
+          details: payload,
+        };
+      },
+    }),
+    { name: "present_artifact" },
+  );
+
+  api.registerTool(
+    () => ({
+      name: "mobcode_open",
+      description:
+        "Open a MobCode app surface using target + params. Supported targets: browser_tab, file, terminal, docker, kubernetes, local_agent, openclaw.",
+      parameters: {
+        type: "object",
+        properties: {
+          target: {
+            type: "string",
+            enum: [
+              "browser_tab",
+              "file",
+              "terminal",
+              "docker",
+              "kubernetes",
+              "local_agent",
+              "openclaw",
+            ],
+          },
+          params: {
+            type: "object",
+            description:
+              "Target-specific params. browser_tab: {url}. file: {path, start_line?, end_line?}. terminal: {command?}. docker/kubernetes/local_agent/openclaw: {section?}.",
+          },
+        },
+        required: ["target"],
+        additionalProperties: false,
+      },
+      execute: async (_toolCallId, rawArgs) => {
+        const payload = validateMobcodeOpenArgs(rawArgs);
+        const client = await store.resolveClientForOpenTarget(payload.target);
+        if (!client?.clientId) {
+          const offlineResult = {
+            ok: false,
+            status: "offline",
+            message: `No active MobCode client supports target=${payload.target}.`,
+          };
+          return {
+            content: [
+              {
+                type: "text",
+                text: buildJsonTextContent(offlineResult),
+              },
+            ],
+            details: offlineResult,
+          };
+        }
+        const action = await store.enqueueClientAction({
+          clientId: client.clientId,
+          type: "mobcode_open",
+          payload,
+        });
+        const resolution = await store.waitForClientActionResolution(action.id, {
+          timeoutMs:
+            typeof rawArgs?.timeout_ms === "number" && Number.isFinite(rawArgs.timeout_ms)
+              ? rawArgs.timeout_ms
+              : 20_000,
+        });
+        const status = String(resolution?.status ?? "").trim() || "timeout";
+        const result = {
+          ok: status === "done",
+          status,
+          clientId: client.clientId,
+          action,
+          ...(resolution?.errorText ? { errorText: resolution.errorText } : {}),
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: buildJsonTextContent(result),
+            },
+          ],
+          details: result,
+        };
+      },
+    }),
+    { name: "mobcode_open" },
+  );
+}