@mobcode/openclaw-plugin 0.1.0 → 0.1.2

package/README.md

@@ -31,9 +31,11 @@
   - `mobcode.client.register`
   - `mobcode.client.actions.wait`
   - `mobcode.client.actions.ack`
- - tools:
+- tools:
   - `present_artifact`
   - `mobcode_open`
+- bundled skill:
+  - `mobcode-ui`
 - HTTP routes:
   - `/plugins/mobcode/health`
   - `/plugins/mobcode/config`
@@ -56,6 +58,7 @@
 - `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.
+- вместе с plugin устанавливается bundled skill `mobcode-ui`, который подсказывает OpenClaw агенту, когда использовать `present_artifact` и `mobcode_open`.
 - real push delivery в FCM/APNs пока не сделана; есть только device registry и queue.
 - file diff flow лучше делать через интеграцию с официальным `diffs` plugin, а не изобретать свой формат.
 - mobile approvals построены поверх существующих `exec.approval.*` методов OpenClaw: plugin хранит state/history, а resolve по-прежнему идет через штатный RPC.

package/openclaw.plugin.json

@@ -2,6 +2,9 @@
   "id": "mobcode",
   "name": "MobCode",
   "description": "MobCode mobile integration plugin for OpenClaw.",
+  "skills": [
+    "skills"
+  ],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobcode/openclaw-plugin",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MobCode integration plugin for OpenClaw",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,7 @@
     "README.md",
     "index.js",
     "openclaw.plugin.json",
+    "skills",
     "src"
   ],
   "keywords": [

package/skills/mobcode-ui/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: mobcode-ui
+description: Guidance for using MobCode rich artifacts and app surfaces from OpenClaw.
+---
+
+# MobCode UI
+
+- You are operating inside MobCode, where the user can view rich artifacts and app surfaces directly in the mobile app.
+- Prefer these tools when they make the result easier to inspect or act on.
+
+## Rich artifacts
+
+- Use `present_artifact` when the result is easier to understand as a structured visual artifact than as a long plain-text reply.
+- Good fits:
+  - dashboards
+  - charts
+  - status cards
+  - multi-section summaries
+  - review results with sections and actions
+- Keep ordinary short answers as normal assistant text. Use artifacts only when structure or visual layout genuinely helps.
+
+### `present_artifact`
+
+- Required argument: `artifact`
+- Optional arguments:
+  - `item_id`
+  - `op` = `start` | `patch` | `done`
+- The artifact document must include:
+  - `artifactId`
+  - `kind`
+  - `title`
+- The artifact can also include:
+  - `summary`
+  - `initialScreenId`
+  - `screens`
+  - `actions`
+  - `media`
+  - `preview`
+  - `metadata`
+
+Use `op="done"` for a one-shot artifact. Use `start` and `patch` only when you are progressively building the same artifact.
+
+## App surfaces
+
+- Use `mobcode_open` when the user should directly inspect something in the MobCode app instead of reading a long explanation.
+- Typical cases:
+  - open a local or forwarded web UI
+  - open a file at a relevant location
+  - jump to the terminal or another MobCode section
+
+### `mobcode_open`
+
+- Required argument: `target`
+- Optional argument: `params`
+
+Supported targets:
+- `browser_tab`
+  - requires `params.url`
+- `file`
+  - requires `params.path`
+  - optional `params.start_line`
+  - optional `params.end_line`
+- `terminal`
+  - optional `params.command`
+- `docker`
+- `kubernetes`
+- `local_agent`
+- `openclaw`
+  - these targets may include optional `params.section`
+
+If the action is not necessary for the user to inspect or interact with something, prefer a normal text reply instead of `mobcode_open`.
+
+## Usage rules
+
+- Prefer plain assistant text for simple answers.
+- Use `present_artifact` for structured visual output.
+- Use `mobcode_open` when the next best user action is to inspect or open something in the app.
+- Do not invent unsupported targets or undocumented artifact fields.

package/src/gateway-methods.js

@@ -1,7 +1,14 @@
-export function registerMobcodeGatewayMethods({ store, builders, featureMatrix, api }) {
+export function registerMobcodeGatewayMethods({
+  store,
+  builders,
+  featureMatrix,
+  pluginMetadata,
+  api,
+}) {
   api.registerGatewayMethod("mobcode.capabilities", async ({ respond }) => {
     respond(true, {
       ok: true,
+      plugin: pluginMetadata,
       features: featureMatrix(),
     });
   });

package/src/openclaw-session-reader.js

@@ -41,7 +41,7 @@ async function readSessionTranscriptMessagesFromInternals(sessionKey) {
   return Array.isArray(rawMessages) ? rawMessages : [];
 }
 
-async function readSessionMessagesThroughChatHistory(config, sessionKey) {
+async function readSessionMessagesThroughChatHistory(config, sessionKey, logger) {
   const normalizedSessionKey = String(sessionKey ?? "").trim();
   if (!normalizedSessionKey) {
     return [];
@@ -56,20 +56,31 @@ async function readSessionMessagesThroughChatHistory(config, sessionKey) {
     clientDisplayName: "MobCode History Backfill",
   });
   const messages = payload?.messages;
+  logger?.info?.(
+    `[mobcode-history] chat.history session=${normalizedSessionKey} messages=${Array.isArray(messages) ? messages.length : 0}`,
+  );
   return Array.isArray(messages) ? messages : [];
 }
 
-export async function readSessionTranscriptMessages(config, sessionKey) {
+export async function readSessionTranscriptMessages(config, sessionKey, logger) {
   try {
     const gatewayMessages = await readSessionMessagesThroughChatHistory(
       config,
       sessionKey,
+      logger,
     );
     if (gatewayMessages.length > 0) {
       return gatewayMessages;
     }
-  } catch {
+  } catch (error) {
+    logger?.warn?.(
+      `[mobcode-history] chat.history failed session=${String(sessionKey ?? "").trim()}: ${error instanceof Error ? error.message : String(error)}`,
+    );
     // Fall back to adjacent-source runtime imports for development checkouts.
   }
-  return readSessionTranscriptMessagesFromInternals(sessionKey);
+  const internalMessages = await readSessionTranscriptMessagesFromInternals(sessionKey);
+  logger?.info?.(
+    `[mobcode-history] internal fallback session=${String(sessionKey ?? "").trim()} messages=${internalMessages.length}`,
+  );
+  return internalMessages;
 }

package/src/plugin-definition.js

@@ -9,6 +9,7 @@ import {
   tryBuildAvailableProvidersPayload,
   tryBuildProviderModelsPayload,
 } from "./openclaw-introspection.js";
+import { readPluginMetadata } from "./plugin-metadata.js";
 import { readSessionTranscriptMessages } from "./openclaw-session-reader.js";
 import { registerMobcodeRuntimeObservers } from "./runtime-events.js";
 import { MobcodeStateStore } from "./state-store.js";
@@ -22,8 +23,10 @@ export function createMobcodePluginDefinition() {
     register(api) {
       const pluginConfig = api.pluginConfig ?? {};
       const stateDir = api.runtime.state.resolveStateDir();
+      const pluginMetadata = readPluginMetadata();
       const store = new MobcodeStateStore({
         rootDir: path.join(stateDir, "plugins", "mobcode"),
+        logger: api.logger,
       });
 
       const builders = {
@@ -33,7 +36,11 @@ export function createMobcodePluginDefinition() {
           await tryBuildProviderModelsPayload(api, providerId),
         ensureSessionMessages: async (sessionKey) => {
           await store.ensureSessionIndexed(sessionKey, async () =>
-            readSessionTranscriptMessages(api.runtime.config.loadConfig(), sessionKey),
+            readSessionTranscriptMessages(
+              api.runtime.config.loadConfig(),
+              sessionKey,
+              api.logger,
+            ),
           );
         },
       };
@@ -43,6 +50,7 @@ export function createMobcodePluginDefinition() {
         store,
         builders,
         featureMatrix: listFeatureMatrix,
+        pluginMetadata,
       });
       registerMobcodeHttpRoutes({
         api,

package/src/plugin-metadata.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+
+const DEFAULT_PLUGIN_METADATA = Object.freeze({
+  id: "mobcode",
+  packageName: "@mobcode/openclaw-plugin",
+  version: "0.0.0",
+});
+
+let cachedPluginMetadata = null;
+
+export function readPluginMetadata() {
+  if (cachedPluginMetadata != null) {
+    return cachedPluginMetadata;
+  }
+
+  try {
+    const packageJsonPath = new URL("../package.json", import.meta.url);
+    const parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    const packageName =
+      typeof parsed?.name === "string" ? parsed.name.trim() : "";
+    const version = typeof parsed?.version === "string" ? parsed.version.trim() : "";
+    cachedPluginMetadata = Object.freeze({
+      id: DEFAULT_PLUGIN_METADATA.id,
+      packageName: packageName.length > 0
+          ? packageName
+          : DEFAULT_PLUGIN_METADATA.packageName,
+      version: version.length > 0 ? version : DEFAULT_PLUGIN_METADATA.version,
+    });
+  } catch (_) {
+    cachedPluginMetadata = DEFAULT_PLUGIN_METADATA;
+  }
+
+  return cachedPluginMetadata;
+}

package/src/state-store.js

@@ -596,8 +596,9 @@ function normalizeApprovalStatus(status, decision) {
 }
 
 export class MobcodeStateStore {
-  constructor({ rootDir }) {
+  constructor({ rootDir, logger = null }) {
     this.rootDir = rootDir;
+    this.logger = logger;
     this.databasePath = path.join(rootDir, "mobcode.sqlite");
     this.database = null;
     this.clientActionWaiters = new Map();
@@ -803,9 +804,16 @@ export class MobcodeStateStore {
       return;
     }
     const existing = this._db()
-      .prepare(`SELECT session_key FROM indexed_sessions WHERE session_key=? LIMIT 1`)
+      .prepare(
+        `SELECT session_key, last_backfill_at
+           FROM indexed_sessions
+          WHERE session_key=?
+          LIMIT 1`,
+      )
       .get(normalizedSessionKey);
-    if (existing) {
+    const alreadyBackfilled =
+      typeof existing?.last_backfill_at === "string" && existing.last_backfill_at.trim().length > 0;
+    if (alreadyBackfilled) {
       return;
     }
     const messages = Array.isArray(loader) ? loader : await loader();
@@ -918,6 +926,9 @@ export class MobcodeStateStore {
     });
 
     transaction(messages);
+    this.logger?.info?.(
+      `[mobcode-store] indexed session=${normalizedSessionKey} messages=${messages.length}`,
+    );
   }
 
   async appendMessage(update) {