@mobcode/openclaw-plugin 0.1.0

package/src/state-store.js

@@ -0,0 +1,1430 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+
+function cloneJson(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function nowMs() {
+  return Date.now();
+}
+
+function toJson(value) {
+  return JSON.stringify(value ?? null);
+}
+
+function fromJson(value, fallback) {
+  if (typeof value !== "string" || !value.trim()) {
+    return cloneJson(fallback);
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    return cloneJson(fallback);
+  }
+}
+
+function normalizeSessionKey(rawSessionKey, rawSessionFile) {
+  const sessionKey = String(rawSessionKey ?? "").trim();
+  if (sessionKey) {
+    return sessionKey;
+  }
+  const sessionFile = String(rawSessionFile ?? "").trim();
+  return sessionFile || "unknown";
+}
+
+function normalizeMessageObject(message, messageId) {
+  if (!message || typeof message !== "object" || Array.isArray(message)) {
+    return {
+      id: messageId ?? null,
+      role: "system",
+      content: [{ type: "text", text: String(message ?? "") }],
+    };
+  }
+  const normalized = cloneJson(message) ?? {};
+  const openclawMeta =
+    normalized.__openclaw && typeof normalized.__openclaw === "object"
+      ? normalized.__openclaw
+      : null;
+  const resolvedMessageId =
+    String(normalized.id ?? messageId ?? openclawMeta?.id ?? "").trim() || null;
+  if (resolvedMessageId && !normalized.id) {
+    normalized.id = resolvedMessageId;
+  }
+  return normalized;
+}
+
+function extractMessageText(message) {
+  const content = message?.content;
+  if (typeof content === "string") {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return "";
+  }
+  return content
+    .map((block) => {
+      if (!block || typeof block !== "object") {
+        return "";
+      }
+      if (typeof block.text === "string") {
+        return block.text;
+      }
+      if (typeof block.content === "string") {
+        return block.content;
+      }
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+function extractThinkingText(message) {
+  const content = message?.content;
+  if (!Array.isArray(content)) {
+    return null;
+  }
+  const parts = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") continue;
+    if (String(block.type ?? "").trim().toLowerCase() !== "thinking") {
+      continue;
+    }
+    const value = typeof block.thinking === "string" ? block.thinking : "";
+    if (value.trim()) {
+      parts.push(value);
+    }
+  }
+  return parts.length > 0 ? parts.join("\n") : null;
+}
+
+function textToDisplayForAssistant(text) {
+  const normalized = typeof text === "string" ? text : String(text ?? "");
+  const trimmed = normalized.trim();
+  if (!trimmed || !trimmed.startsWith("{")) {
+    return normalized;
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      !Array.isArray(parsed) &&
+      ((Object.prototype.hasOwnProperty.call(parsed, "ok") &&
+        Object.prototype.hasOwnProperty.call(parsed, "result")) ||
+        Object.prototype.hasOwnProperty.call(parsed, "restart") ||
+        Object.prototype.hasOwnProperty.call(parsed, "sentinel"))
+    ) {
+      return "";
+    }
+  } catch {
+    return normalized;
+  }
+  return normalized;
+}
+
+function decodeMobcodePayload(value) {
+  if (!value) return null;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed || !trimmed.startsWith("{")) {
+      return null;
+    }
+    try {
+      const decoded = JSON.parse(trimmed);
+      return decoded && typeof decoded === "object" && !Array.isArray(decoded) ? decoded : null;
+    } catch {
+      return null;
+    }
+  }
+  if (Array.isArray(value)) {
+    for (const block of value) {
+      if (!block || typeof block !== "object") continue;
+      const type = String(block.type ?? "").trim().toLowerCase();
+      if (type !== "text" && type !== "output_text" && type !== "input_text") {
+        continue;
+      }
+      const decoded = decodeMobcodePayload(block.text ?? block.content ?? "");
+      if (decoded) return decoded;
+    }
+    return null;
+  }
+  if (typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  return null;
+}
+
+function extractMobcodeContentBlocksFromToolResult(rawResult) {
+  const payload = decodeMobcodePayload(rawResult);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return [];
+  }
+  return Array.isArray(payload.content_blocks)
+    ? cloneJson(payload.content_blocks) ?? []
+    : [];
+}
+
+function timelineTextPreview(timeline) {
+  if (!Array.isArray(timeline) || timeline.length === 0) {
+    return "";
+  }
+  const parts = [];
+  for (const item of timeline) {
+    if (!item || typeof item !== "object") continue;
+    const kind = String(item.kind ?? "").trim().toLowerCase();
+    if (kind === "text") {
+      const text = String(item.text ?? "");
+      if (text.trim()) parts.push(text);
+      continue;
+    }
+    if (kind === "step") {
+      const title = String(item.title ?? "");
+      const detail = String(item.detail ?? "");
+      if (title.trim()) parts.push(title);
+      if (detail.trim()) parts.push(detail);
+      continue;
+    }
+    if (kind === "artifact") {
+      const title = String(item?.block?.title ?? "");
+      if (title.trim()) parts.push(title);
+      continue;
+    }
+    if (kind === "question") {
+      const title = String(item.title ?? item?.payload?.title ?? "");
+      if (title.trim()) parts.push(title);
+    }
+  }
+  return parts.join("\n");
+}
+
+function stableId(prefix, seed) {
+  const digest = crypto.createHash("sha1").update(`${prefix}\n${seed}`).digest("hex");
+  return `${prefix}-${digest.slice(0, 12)}`;
+}
+
+function createTextTimelineItem({ id, text, status = "done" }) {
+  return {
+    id,
+    kind: "text",
+    status,
+    text,
+  };
+}
+
+function createToolTimelineItem({ id, toolCall }) {
+  const status = toolCall.isError
+    ? "error"
+    : toolCall.phase === "result"
+      ? "done"
+      : "streaming";
+  return {
+    id,
+    kind: "tool",
+    status,
+    toolCallId: toolCall.toolCallId,
+    ...(toolCall.approvalId ? { approvalId: toolCall.approvalId } : {}),
+    name: toolCall.name,
+    args: cloneJson(toolCall.args),
+    result: cloneJson(toolCall.result),
+    isError: toolCall.isError === true,
+    phase: toolCall.phase,
+  };
+}
+
+function timelineItemFromContentBlock(block, seed) {
+  if (!block || typeof block !== "object") {
+    return null;
+  }
+  const type = String(block.type ?? "").trim().toLowerCase();
+  if (type === "text") {
+    const text = String(block.text ?? "");
+    if (!text.trim()) return null;
+    return createTextTimelineItem({
+      id: stableId("timeline-text", `${seed}\n${text}`),
+      text,
+      status: "done",
+    });
+  }
+  if (type === "artifact_ref") {
+    return {
+      id: stableId("timeline-artifact", `${seed}\n${JSON.stringify(block)}`),
+      kind: "artifact",
+      status: "done",
+      block: cloneJson(block),
+    };
+  }
+  if (type === "question") {
+    return {
+      id: stableId("timeline-question", `${seed}\n${JSON.stringify(block)}`),
+      kind: "question",
+      status: "done",
+      payload: cloneJson(block),
+      ...cloneJson(block),
+    };
+  }
+  return {
+    id: stableId("timeline-unknown", `${seed}\n${JSON.stringify(block)}`),
+    kind: "unknown",
+    status: "error",
+    block: cloneJson(block),
+  };
+}
+
+function extractArtifactDocumentFromMessage(message) {
+  if (!message || typeof message !== "object" || Array.isArray(message)) {
+    return null;
+  }
+  const directPayload = decodeMobcodePayload(message.content);
+  if (directPayload?.artifact && typeof directPayload.artifact === "object") {
+    return directPayload.artifact;
+  }
+  if (Array.isArray(message.content)) {
+    for (const block of message.content) {
+      if (!block || typeof block !== "object") continue;
+      if (block.type === "toolresult" || block.type === "tool_result") {
+        const payload = decodeMobcodePayload(block.content ?? block.result ?? block.output);
+        if (payload?.artifact && typeof payload.artifact === "object") {
+          return payload.artifact;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function createConversationMessage({ id, role, text = "", replyToId = null, replyPreview = null }) {
+  return {
+    id,
+    role,
+    text,
+    status: "done",
+    toolCalls: [],
+    contentBlocks: [],
+    timeline: [],
+    ...(replyToId ? { replyToId } : {}),
+    ...(replyPreview ? { replyPreview } : {}),
+  };
+}
+
+function upsertToolCall(message, toolCall, seed) {
+  const toolCalls = Array.isArray(message.toolCalls) ? [...message.toolCalls] : [];
+  const toolIndex = toolCalls.findIndex((item) => item?.toolCallId === toolCall.toolCallId);
+  if (toolIndex >= 0) {
+    toolCalls[toolIndex] = { ...toolCalls[toolIndex], ...cloneJson(toolCall) };
+  } else {
+    toolCalls.push(cloneJson(toolCall));
+  }
+
+  const timeline = Array.isArray(message.timeline) ? [...message.timeline] : [];
+  const timelineIndex = timeline.findIndex(
+    (item) => item?.kind === "tool" && item?.toolCallId === toolCall.toolCallId,
+  );
+  const toolItem = createToolTimelineItem({
+    id: timelineIndex >= 0 ? timeline[timelineIndex].id : stableId("timeline-tool", seed),
+    toolCall,
+  });
+  if (timelineIndex >= 0) {
+    timeline[timelineIndex] = toolItem;
+  } else {
+    timeline.push(toolItem);
+  }
+
+  return {
+    ...message,
+    toolCalls,
+    timeline,
+    text: timelineTextPreview(timeline) || message.text || "",
+  };
+}
+
+function appendAssistantTextSegment(message, text, seed) {
+  if (!String(text ?? "").trim()) {
+    return message;
+  }
+  const normalizedText = String(text);
+  const timeline = Array.isArray(message.timeline) ? [...message.timeline] : [];
+  const last = timeline.length > 0 ? timeline[timeline.length - 1] : null;
+  if (last?.kind === "text" && last?.status === "streaming") {
+    timeline[timeline.length - 1] = {
+      ...last,
+      text: `${String(last.text ?? "")}${normalizedText}`,
+      status: "done",
+    };
+  } else {
+    timeline.push(
+      createTextTimelineItem({
+        id: stableId("timeline-text", `${seed}\n${timeline.length}`),
+        text: normalizedText,
+        status: "done",
+      }),
+    );
+  }
+  return {
+    ...message,
+    timeline,
+    text: timelineTextPreview(timeline) || message.text || "",
+  };
+}
+
+function appendToolResult(message, { toolCallId, result, isError }, seed) {
+  const existingTool =
+    (Array.isArray(message.toolCalls)
+      ? message.toolCalls.find((item) => item?.toolCallId === toolCallId)
+      : null) ?? {
+      toolCallId,
+      name: "unknown",
+      phase: "result",
+      result: null,
+      isError: false,
+    };
+  let next = upsertToolCall(
+    message,
+    {
+      ...existingTool,
+      result: cloneJson(result),
+      isError: isError === true,
+      phase: "result",
+    },
+    `${seed}\n${toolCallId}`,
+  );
+
+  const blocks = extractMobcodeContentBlocksFromToolResult(result);
+  if (blocks.length === 0) {
+    return next;
+  }
+
+  const contentBlocks = Array.isArray(next.contentBlocks) ? [...next.contentBlocks] : [];
+  const timeline = Array.isArray(next.timeline) ? [...next.timeline] : [];
+  const seenBlockKeys = new Set(contentBlocks.map((block) => JSON.stringify(block)));
+  const seenTimelineKeys = new Set(timeline.map((item) => JSON.stringify(item)));
+  for (const block of blocks) {
+    const blockKey = JSON.stringify(block);
+    if (!seenBlockKeys.has(blockKey)) {
+      seenBlockKeys.add(blockKey);
+      contentBlocks.push(cloneJson(block));
+    }
+    const item = timelineItemFromContentBlock(block, `${seed}\n${blockKey}`);
+    if (!item) continue;
+    const timelineKey = JSON.stringify(item);
+    if (!seenTimelineKeys.has(timelineKey)) {
+      seenTimelineKeys.add(timelineKey);
+      timeline.push(item);
+    }
+  }
+  return {
+    ...next,
+    contentBlocks,
+    timeline,
+    text: timelineTextPreview(timeline) || next.text || "",
+  };
+}
+
+function appendAssistantTranscriptContent(message, content, seed) {
+  if (!Array.isArray(content)) {
+    return appendAssistantTextSegment(
+      message,
+      textToDisplayForAssistant(extractMessageText({ content })),
+      seed,
+    );
+  }
+
+  let next = { ...message };
+  for (const rawBlock of content) {
+    if (!rawBlock || typeof rawBlock !== "object") continue;
+    const block = cloneJson(rawBlock) ?? {};
+    const type = String(block.type ?? "").trim().toLowerCase();
+    if (type === "text" || type === "output_text" || type === "input_text") {
+      next = appendAssistantTextSegment(
+        next,
+        textToDisplayForAssistant(String(block.text ?? block.content ?? "")),
+        `${seed}\ntext`,
+      );
+      continue;
+    }
+    if (type === "toolcall" || type === "tool_call") {
+      const toolCallId = String(block.id ?? "").trim();
+      if (!toolCallId) continue;
+      next = upsertToolCall(
+        next,
+        {
+          toolCallId,
+          approvalId: String(block.approvalId ?? block.approval_id ?? "").trim() || null,
+          name: String(block.name ?? "unknown"),
+          args: cloneJson(block.arguments ?? block.args),
+          result: null,
+          isError: false,
+          phase: "start",
+        },
+        `${seed}\n${toolCallId}`,
+      );
+      continue;
+    }
+    if (type === "toolresult" || type === "tool_result") {
+      const toolCallId = String(block.toolCallId ?? block.tool_call_id ?? "").trim();
+      if (!toolCallId) continue;
+      next = appendToolResult(
+        next,
+        {
+          toolCallId,
+          result: block.content ?? block.result ?? block.output,
+          isError: block.isError === true || block.is_error === true,
+        },
+        `${seed}\n${toolCallId}`,
+      );
+      continue;
+    }
+  }
+  return next;
+}
+
+function projectConversationMessages(rawMessages, sessionKey) {
+  const projected = [];
+  const assistantIndexByRunId = new Map();
+
+  for (const rawMessage of rawMessages) {
+    const message = normalizeMessageObject(rawMessage, rawMessage?.id ?? null);
+    const role = String(message?.role ?? "").trim().toLowerCase();
+    const runId = String(message?.runId ?? message?.run_id ?? "").trim();
+    const messageId =
+      String(message?.id ?? "").trim() ||
+      stableId("message", `${sessionKey}\n${role}\n${JSON.stringify(message)}`);
+
+    if (role === "user" || role === "system") {
+      projected.push(
+        createConversationMessage({
+          id: messageId,
+          role,
+          text: extractMessageText(message),
+        }),
+      );
+      continue;
+    }
+
+    if (role === "assistant") {
+      const assistantIndex = runId ? assistantIndexByRunId.get(runId) : undefined;
+      const current =
+        assistantIndex == null
+          ? createConversationMessage({
+              id: messageId,
+              role: "assistant",
+              text: "",
+            })
+          : projected[assistantIndex];
+      let next = appendAssistantTranscriptContent(
+        {
+          ...current,
+          thinking: extractThinkingText(message) ?? current.thinking ?? null,
+        },
+        message.content,
+        `${sessionKey}\n${messageId}`,
+      );
+      if (assistantIndex == null) {
+        projected.push(next);
+        if (runId) {
+          assistantIndexByRunId.set(runId, projected.length - 1);
+        }
+      } else {
+        projected[assistantIndex] = next;
+      }
+      continue;
+    }
+
+    if (role === "toolresult" || role === "tool_result") {
+      const toolCallId = String(message?.toolCallId ?? message?.tool_call_id ?? "").trim();
+      if (!toolCallId) {
+        continue;
+      }
+      const assistantIndex = runId
+        ? assistantIndexByRunId.get(runId)
+        : projected.map((item) => item.role).lastIndexOf("assistant");
+      if (assistantIndex == null || assistantIndex < 0) {
+        continue;
+      }
+      projected[assistantIndex] = appendToolResult(
+        projected[assistantIndex],
+        {
+          toolCallId,
+          result: decodeMobcodePayload(message.content) ?? message.content,
+          isError: message.isError === true || message.is_error === true,
+        },
+        `${sessionKey}\n${messageId}`,
+      );
+    }
+  }
+
+  return projected.map((item) => ({
+    ...item,
+    status: "done",
+    text: timelineTextPreview(item.timeline) || item.text || "",
+  }));
+}
+
+function createMessageSourceKey(sessionKey, messageId, normalizedMessage) {
+  if (messageId) {
+    return `mid:${sessionKey}:${messageId}`;
+  }
+  const digest = crypto
+    .createHash("sha256")
+    .update(`${sessionKey}\n${JSON.stringify(normalizedMessage)}`)
+    .digest("hex");
+  return `hash:${digest}`;
+}
+
+function normalizeApprovalDecision(decision) {
+  const normalized = String(decision ?? "").trim().toLowerCase();
+  switch (normalized) {
+    case "allow-once":
+      return "allow-once";
+    case "allow-always":
+      return "allow-always";
+    case "deny":
+      return "deny";
+    default:
+      return null;
+  }
+}
+
+function normalizeApprovalStatus(status, decision) {
+  if (status === "pending") {
+    return "pending";
+  }
+  const normalizedDecision = normalizeApprovalDecision(decision);
+  return normalizedDecision ?? "resolved";
+}
+
+export class MobcodeStateStore {
+  constructor({ rootDir }) {
+    this.rootDir = rootDir;
+    this.databasePath = path.join(rootDir, "mobcode.sqlite");
+    this.database = null;
+    this.clientActionWaiters = new Map();
+    this.clientActionResolutionWaiters = new Map();
+  }
+
+  async init() {
+    await fs.mkdir(this.rootDir, { recursive: true });
+    if (this.database) {
+      return;
+    }
+    this.database = new DatabaseSync(this.databasePath);
+    this.database.exec(`
+      PRAGMA journal_mode = WAL;
+      PRAGMA foreign_keys = ON;
+
+      CREATE TABLE IF NOT EXISTS devices (
+        platform TEXT NOT NULL,
+        token TEXT NOT NULL,
+        metadata_json TEXT NOT NULL DEFAULT '{}',
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (platform, token)
+      );
+
+      CREATE TABLE IF NOT EXISTS push_queue (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        type TEXT NOT NULL,
+        session_key TEXT,
+        payload_json TEXT NOT NULL,
+        queued_at TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS indexed_sessions (
+        session_key TEXT PRIMARY KEY,
+        last_backfill_at TEXT,
+        updated_at TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS messages (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_key TEXT NOT NULL,
+        source_key TEXT NOT NULL UNIQUE,
+        message_id TEXT,
+        role TEXT,
+        text TEXT,
+        raw_json TEXT NOT NULL,
+        created_at_ms INTEGER NOT NULL,
+        indexed_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_messages_session_id_desc
+        ON messages(session_key, id DESC);
+
+      CREATE TABLE IF NOT EXISTS approvals (
+        approval_id TEXT PRIMARY KEY,
+        session_key TEXT,
+        command TEXT NOT NULL,
+        cwd TEXT,
+        host TEXT,
+        security TEXT,
+        ask TEXT,
+        created_at_ms INTEGER NOT NULL,
+        expires_at_ms INTEGER NOT NULL,
+        status TEXT NOT NULL,
+        decision TEXT,
+        resolved_at_ms INTEGER,
+        request_json TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_approvals_session_created
+        ON approvals(session_key, created_at_ms DESC);
+
+      CREATE INDEX IF NOT EXISTS idx_approvals_status_created
+        ON approvals(status, created_at_ms DESC);
+
+      CREATE TABLE IF NOT EXISTS artifacts (
+        artifact_id TEXT PRIMARY KEY,
+        session_key TEXT,
+        run_id TEXT,
+        kind TEXT NOT NULL,
+        title TEXT NOT NULL,
+        summary TEXT,
+        document_json TEXT NOT NULL,
+        created_at_ms INTEGER NOT NULL,
+        updated_at_ms INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_artifacts_session_updated
+        ON artifacts(session_key, updated_at_ms DESC);
+
+      CREATE TABLE IF NOT EXISTS artifact_blobs (
+        blob_id TEXT PRIMARY KEY,
+        artifact_id TEXT NOT NULL,
+        mime_type TEXT,
+        file_name TEXT,
+        storage_path TEXT NOT NULL,
+        created_at_ms INTEGER NOT NULL,
+        updated_at_ms INTEGER NOT NULL,
+        FOREIGN KEY (artifact_id) REFERENCES artifacts(artifact_id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_artifact_blobs_artifact_updated
+        ON artifact_blobs(artifact_id, updated_at_ms DESC);
+
+      CREATE TABLE IF NOT EXISTS client_sessions (
+        client_id TEXT PRIMARY KEY,
+        session_key TEXT,
+        platform TEXT,
+        app_version TEXT,
+        capabilities_json TEXT NOT NULL,
+        last_seen_at_ms INTEGER NOT NULL,
+        updated_at_ms INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_client_sessions_seen
+        ON client_sessions(last_seen_at_ms DESC);
+
+      CREATE TABLE IF NOT EXISTS client_actions (
+        action_id TEXT PRIMARY KEY,
+        client_id TEXT NOT NULL,
+        type TEXT NOT NULL,
+        payload_json TEXT NOT NULL,
+        status TEXT NOT NULL,
+        created_at_ms INTEGER NOT NULL,
+        acked_at_ms INTEGER,
+        error_text TEXT,
+        FOREIGN KEY (client_id) REFERENCES client_sessions(client_id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_client_actions_client_status_created
+        ON client_actions(client_id, status, created_at_ms ASC);
+    `);
+  }
+
+  _db() {
+    if (!this.database) {
+      throw new Error("MobCode store not initialized");
+    }
+    return this.database;
+  }
+
+  async readDevices() {
+    const rows = this._db()
+      .prepare(
+        `SELECT platform, token, metadata_json, updated_at
+           FROM devices
+          ORDER BY updated_at DESC`,
+      )
+      .all();
+    return {
+      devices: rows.map((row) => ({
+        platform: row.platform,
+        token: row.token,
+        ...(fromJson(row.metadata_json, {}) ?? {}),
+        updatedAt: row.updated_at,
+      })),
+    };
+  }
+
+  async upsertDevice(device) {
+    const platform = String(device?.platform ?? "").trim();
+    const token = String(device?.token ?? "").trim();
+    if (!platform || !token) {
+      throw new Error("platform and token are required");
+    }
+    const now = new Date().toISOString();
+    const metadata = { ...device };
+    delete metadata.platform;
+    delete metadata.token;
+    this._db()
+      .prepare(
+        `INSERT INTO devices(platform, token, metadata_json, updated_at)
+         VALUES(?, ?, ?, ?)
+         ON CONFLICT(platform, token) DO UPDATE SET
+           metadata_json=excluded.metadata_json,
+           updated_at=excluded.updated_at`,
+      )
+      .run(platform, token, toJson(metadata), now);
+    return this.readDevices();
+  }
+
+  async enqueuePush(item) {
+    const queuedAt = new Date().toISOString();
+    this._db()
+      .prepare(
+        `INSERT INTO push_queue(type, session_key, payload_json, queued_at)
+         VALUES(?, ?, ?, ?)`,
+      )
+      .run(
+        String(item?.type ?? "unknown"),
+        item?.sessionKey ? String(item.sessionKey) : null,
+        toJson(item),
+        queuedAt,
+      );
+    const row = this._db().prepare(`SELECT COUNT(*) AS count FROM push_queue`).get();
+    return { queued: Number(row?.count ?? 0) };
+  }
+
+  async ensureSessionIndexed(sessionKey, loader) {
+    const normalizedSessionKey = String(sessionKey ?? "").trim();
+    if (!normalizedSessionKey) {
+      return;
+    }
+    const existing = this._db()
+      .prepare(`SELECT session_key FROM indexed_sessions WHERE session_key=? LIMIT 1`)
+      .get(normalizedSessionKey);
+    if (existing) {
+      return;
+    }
+    const messages = Array.isArray(loader) ? loader : await loader();
+    await this.indexSessionMessages(normalizedSessionKey, messages);
+    const now = new Date().toISOString();
+    this._db()
+      .prepare(
+        `INSERT INTO indexed_sessions(session_key, last_backfill_at, updated_at)
+         VALUES(?, ?, ?)
+         ON CONFLICT(session_key) DO UPDATE SET
+           last_backfill_at=excluded.last_backfill_at,
+           updated_at=excluded.updated_at`,
+      )
+      .run(normalizedSessionKey, now, now);
+  }
+
+  async indexSessionMessages(sessionKey, messages) {
+    const normalizedSessionKey = String(sessionKey ?? "").trim();
+    if (!normalizedSessionKey || !Array.isArray(messages) || messages.length == 0) {
+      return;
+    }
+
+    const insert = this._db().prepare(
+      `INSERT OR IGNORE INTO messages(
+         session_key,
+         source_key,
+         message_id,
+         role,
+         text,
+         raw_json,
+         created_at_ms,
+         indexed_at
+       ) VALUES(?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    const touchSession = this._db().prepare(
+      `INSERT INTO indexed_sessions(session_key, updated_at)
+       VALUES(?, ?)
+       ON CONFLICT(session_key) DO UPDATE SET updated_at=excluded.updated_at`,
+    );
+    const upsertArtifact = this._db().prepare(
+      `INSERT INTO artifacts(
+         artifact_id,
+         session_key,
+         run_id,
+         kind,
+         title,
+         summary,
+         document_json,
+         created_at_ms,
+         updated_at_ms
+       ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(artifact_id) DO UPDATE SET
+         session_key=excluded.session_key,
+         run_id=excluded.run_id,
+         kind=excluded.kind,
+         title=excluded.title,
+         summary=excluded.summary,
+         document_json=excluded.document_json,
+         updated_at_ms=excluded.updated_at_ms`,
+    );
+    const now = new Date().toISOString();
+
+    const transaction = this._db().transaction((items) => {
+      for (const item of items) {
+        const normalizedMessage = normalizeMessageObject(item, item?.id ?? null);
+        const messageId = String(normalizedMessage?.id ?? "").trim() || null;
+        const sourceKey = createMessageSourceKey(
+          normalizedSessionKey,
+          messageId,
+          normalizedMessage,
+        );
+        const timestampRaw =
+          normalizedMessage?.timestamp ?? normalizedMessage?.createdAt ?? Date.now();
+        const createdAtMs =
+          typeof timestampRaw === "number"
+            ? timestampRaw
+            : Number.parseInt(String(timestampRaw), 10) || Date.now();
+
+        insert.run(
+          normalizedSessionKey,
+          sourceKey,
+          messageId,
+          String(normalizedMessage?.role ?? "").trim() || null,
+          extractMessageText(normalizedMessage),
+          toJson(normalizedMessage),
+          createdAtMs,
+          now,
+        );
+        const artifactDocument = extractArtifactDocumentFromMessage(normalizedMessage);
+        const artifactId = String(
+          artifactDocument?.artifactId ?? artifactDocument?.artifact_id ?? "",
+        ).trim();
+        const artifactKind = String(artifactDocument?.kind ?? "").trim();
+        const artifactTitle = String(artifactDocument?.title ?? "").trim();
+        if (artifactId && artifactKind && artifactTitle) {
+          upsertArtifact.run(
+            artifactId,
+            normalizedSessionKey,
+            String(normalizedMessage?.runId ?? normalizedMessage?.run_id ?? "").trim() || null,
+            artifactKind,
+            artifactTitle,
+            String(artifactDocument?.summary ?? "").trim() || null,
+            toJson(artifactDocument),
+            createdAtMs,
+            createdAtMs,
+          );
+        }
+      }
+      touchSession.run(normalizedSessionKey, now);
+    });
+
+    transaction(messages);
+  }
+
+  async appendMessage(update) {
+    const sessionKey = normalizeSessionKey(update?.sessionKey, update?.sessionFile);
+    const normalizedMessage = normalizeMessageObject(update?.message, update?.messageId);
+    await this.indexSessionMessages(sessionKey, [normalizedMessage]);
+    const row = this._db()
+      .prepare(`SELECT COUNT(*) AS count FROM messages WHERE session_key=?`)
+      .get(sessionKey);
+    return { sessionKey, count: Number(row?.count ?? 0) };
+  }
+
+  async pageTranscriptMessages(sessionKey) {
+    const normalizedSessionKey = String(sessionKey ?? "").trim();
+    const rows = this._db()
+      .prepare(
+        `SELECT id, message_id, raw_json
+           FROM messages
+          WHERE session_key=?
+          ORDER BY id ASC`,
+      )
+      .all(normalizedSessionKey);
+    return rows.map((row) => {
+      const message = fromJson(row.raw_json, {});
+      if (message && typeof message === "object" && !Array.isArray(message) && !message.id) {
+        message.id = row.message_id ?? null;
+      }
+      return message;
+    });
+  }
+
+  async pageSessionMessages(sessionKey, { limit = 100, beforeId } = {}) {
+    const normalizedSessionKey = String(sessionKey ?? "").trim();
+    const normalizedLimit = Math.max(1, Math.min(Number(limit) || 100, 500));
+    const normalizedBeforeId =
+      typeof beforeId === "number" && Number.isFinite(beforeId) ? beforeId : null;
+    const transcriptMessages = await this.pageTranscriptMessages(normalizedSessionKey);
+    const projected = projectConversationMessages(transcriptMessages, normalizedSessionKey);
+    const endExclusive = normalizedBeforeId == null
+      ? projected.length
+      : Math.max(0, Math.min(projected.length, normalizedBeforeId - 1));
+    const start = Math.max(0, endExclusive - normalizedLimit);
+    const items = projected.slice(start, endExclusive);
+    const hasMore = start > 0;
+    const nextBeforeId = hasMore ? start + 1 : null;
+
+    return {
+      sessionKey: normalizedSessionKey,
+      items,
+      rawMessages: transcriptMessages,
+      nextBeforeId,
+      hasMore,
+      total: projected.length,
+    };
+  }
+
+  async listSessionMessages(sessionKey) {
+    const page = await this.pageSessionMessages(sessionKey, { limit: 500 });
+    return page.items;
+  }
+
+  async recordApprovalRequested(payload) {
+    const request = payload?.request && typeof payload.request === "object" ? payload.request : {};
+    const approvalId = String(payload?.id ?? "").trim();
+    if (!approvalId) {
+      return;
+    }
+    const now = new Date().toISOString();
+    this._db()
+      .prepare(
+        `INSERT INTO approvals(
+           approval_id,
+           session_key,
+           command,
+           cwd,
+           host,
+           security,
+           ask,
+           created_at_ms,
+           expires_at_ms,
+           status,
+           decision,
+           resolved_at_ms,
+           request_json,
+           updated_at
+         ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', NULL, NULL, ?, ?)
+         ON CONFLICT(approval_id) DO UPDATE SET
+           session_key=excluded.session_key,
+           command=excluded.command,
+           cwd=excluded.cwd,
+           host=excluded.host,
+           security=excluded.security,
+           ask=excluded.ask,
+           created_at_ms=excluded.created_at_ms,
+           expires_at_ms=excluded.expires_at_ms,
+           status='pending',
+           decision=NULL,
+           resolved_at_ms=NULL,
+           request_json=excluded.request_json,
+           updated_at=excluded.updated_at`,
+      )
+      .run(
+        approvalId,
+        String(request.sessionKey ?? "").trim() || null,
+        String(request.command ?? ""),
+        String(request.cwd ?? "").trim() || null,
+        String(request.host ?? "").trim() || null,
+        String(request.security ?? "").trim() || null,
+        String(request.ask ?? "").trim() || null,
+        Number(payload?.createdAtMs ?? nowMs()),
+        Number(payload?.expiresAtMs ?? nowMs()),
+        toJson(payload),
+        now,
+      );
+  }
+
+  async recordApprovalResolved(payload) {
+    const approvalId = String(payload?.id ?? "").trim();
+    if (!approvalId) {
+      return;
+    }
+    const decision = normalizeApprovalDecision(payload?.decision);
+    const now = new Date().toISOString();
+    const resolvedAtMs =
+      typeof payload?.ts === "number" && Number.isFinite(payload.ts) ? payload.ts : nowMs();
+    this._db()
+      .prepare(
+        `UPDATE approvals
+            SET status=?,
+                decision=?,
+                resolved_at_ms=?,
+                updated_at=?
+          WHERE approval_id=?`,
+      )
+      .run(
+        normalizeApprovalStatus("resolved", decision),
+        decision,
+        resolvedAtMs,
+        now,
+        approvalId,
+      );
+  }
+
+  async listApprovals({ sessionKey, status = "pending", limit = 100 } = {}) {
+    const normalizedSessionKey = String(sessionKey ?? "").trim();
+    const normalizedStatus = String(status ?? "").trim().toLowerCase();
+    const normalizedLimit = Math.max(1, Math.min(Number(limit) || 100, 500));
+    const rows =
+      normalizedSessionKey
+        ? this._db()
+            .prepare(
+              `SELECT *
+                 FROM approvals
+                WHERE session_key=? AND status=?
+                ORDER BY created_at_ms DESC
+                LIMIT ?`,
+            )
+            .all(normalizedSessionKey, normalizedStatus, normalizedLimit)
+        : this._db()
+            .prepare(
+              `SELECT *
+                 FROM approvals
+                WHERE status=?
+                ORDER BY created_at_ms DESC
+                LIMIT ?`,
+            )
+            .all(normalizedStatus, normalizedLimit);
+
+    return rows
+      .map((row) => {
+        const payload = fromJson(row.request_json, {});
+        const request =
+          payload?.request && typeof payload.request === "object" ? payload.request : {};
+        return {
+          id: row.approval_id,
+          request: {
+            ...request,
+            command: row.command,
+            cwd: row.cwd,
+            host: row.host,
+            security: row.security,
+            ask: row.ask,
+            sessionKey: row.session_key,
+          },
+          createdAtMs: row.created_at_ms,
+          expiresAtMs: row.expires_at_ms,
+          status: row.status,
+          decision: row.decision,
+          resolvedAtMs: row.resolved_at_ms,
+        };
+      })
+      .reverse();
+  }
+
+  async upsertArtifact({ sessionKey, runId, document }) {
+    const artifactId = String(document?.artifactId ?? document?.artifact_id ?? "").trim();
+    if (!artifactId) {
+      throw new Error("artifactId is required");
+    }
+    const kind = String(document?.kind ?? "").trim();
+    const title = String(document?.title ?? "").trim();
+    if (!kind || !title) {
+      throw new Error("artifact kind and title are required");
+    }
+    const timestamp = nowMs();
+    this._db()
+      .prepare(
+        `INSERT INTO artifacts(
+           artifact_id,
+           session_key,
+           run_id,
+           kind,
+           title,
+           summary,
+           document_json,
+           created_at_ms,
+           updated_at_ms
+         ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(artifact_id) DO UPDATE SET
+           session_key=excluded.session_key,
+           run_id=excluded.run_id,
+           kind=excluded.kind,
+           title=excluded.title,
+           summary=excluded.summary,
+           document_json=excluded.document_json,
+           updated_at_ms=excluded.updated_at_ms`,
+      )
+      .run(
+        artifactId,
+        String(sessionKey ?? "").trim() || null,
+        String(runId ?? "").trim() || null,
+        kind,
+        title,
+        String(document?.summary ?? "").trim() || null,
+        toJson(document),
+        timestamp,
+        timestamp,
+      );
+    return this.readArtifactById(artifactId);
+  }
+
+  async readArtifactById(artifactId) {
+    const normalized = String(artifactId ?? "").trim();
+    if (!normalized) return null;
+    const row = this._db()
+      .prepare(`SELECT * FROM artifacts WHERE artifact_id=? LIMIT 1`)
+      .get(normalized);
+    if (!row) return null;
+    return {
+      artifactId: row.artifact_id,
+      sessionKey: row.session_key,
+      runId: row.run_id,
+      kind: row.kind,
+      title: row.title,
+      summary: row.summary,
+      document: fromJson(row.document_json, null),
+      createdAtMs: row.created_at_ms,
+      updatedAtMs: row.updated_at_ms,
+    };
+  }
+
+  async resolveArtifactBlobPath(blobId) {
+    const normalized = String(blobId ?? "").trim();
+    if (!normalized) return null;
+    const row = this._db()
+      .prepare(`SELECT storage_path FROM artifact_blobs WHERE blob_id=? LIMIT 1`)
+      .get(normalized);
+    const storagePath = String(row?.storage_path ?? "").trim();
+    return storagePath || null;
+  }
+
+  async registerClientSession({ clientId, sessionKey, platform, appVersion, capabilities }) {
+    const normalizedClientId = String(clientId ?? "").trim();
+    if (!normalizedClientId) {
+      throw new Error("clientId is required");
+    }
+    const timestamp = nowMs();
+    this._db()
+      .prepare(
+        `INSERT INTO client_sessions(
+           client_id,
+           session_key,
+           platform,
+           app_version,
+           capabilities_json,
+           last_seen_at_ms,
+           updated_at_ms
+         ) VALUES(?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(client_id) DO UPDATE SET
+           session_key=excluded.session_key,
+           platform=excluded.platform,
+           app_version=excluded.app_version,
+           capabilities_json=excluded.capabilities_json,
+           last_seen_at_ms=excluded.last_seen_at_ms,
+           updated_at_ms=excluded.updated_at_ms`,
+      )
+      .run(
+        normalizedClientId,
+        String(sessionKey ?? "").trim() || null,
+        String(platform ?? "").trim() || null,
+        String(appVersion ?? "").trim() || null,
+        toJson(capabilities ?? {}),
+        timestamp,
+        timestamp,
+      );
+    return {
+      clientId: normalizedClientId,
+      sessionKey: String(sessionKey ?? "").trim() || null,
+      lastSeenAtMs: timestamp,
+    };
+  }
+
+  async resolveClientForOpenTarget(target) {
+    const normalizedTarget = String(target ?? "").trim().toLowerCase();
+    if (!normalizedTarget) return null;
+    const freshnessCutoff = nowMs() - 30_000;
+    const rows = this._db()
+      .prepare(
+        `SELECT client_id, session_key, platform, app_version, capabilities_json, last_seen_at_ms
+           FROM client_sessions
+          WHERE last_seen_at_ms >= ?
+          ORDER BY last_seen_at_ms DESC`,
+      )
+      .all(freshnessCutoff);
+    for (const row of rows) {
+      const capabilities = fromJson(row.capabilities_json, {}) ?? {};
+      const openCapabilities =
+        capabilities?.mobcode_open && typeof capabilities.mobcode_open === "object"
+          ? capabilities.mobcode_open
+          : {};
+      const targets = Array.isArray(openCapabilities.targets) ? openCapabilities.targets : [];
+      if (targets.map((value) => String(value).trim().toLowerCase()).includes(normalizedTarget)) {
+        return {
+          clientId: row.client_id,
+          sessionKey: row.session_key,
+          platform: row.platform,
+          appVersion: row.app_version,
+        };
+      }
+    }
+    return null;
+  }
+
+  async enqueueClientAction({ clientId, type, payload }) {
+    const normalizedClientId = String(clientId ?? "").trim();
+    const normalizedType = String(type ?? "").trim();
+    if (!normalizedClientId || !normalizedType) {
+      throw new Error("clientId and type are required");
+    }
+    const actionId = crypto.randomUUID();
+    const createdAtMs = nowMs();
+    this._db()
+      .prepare(
+        `INSERT INTO client_actions(
+           action_id,
+           client_id,
+           type,
+           payload_json,
+           status,
+           created_at_ms
+         ) VALUES(?, ?, ?, ?, 'pending', ?)`,
+      )
+      .run(actionId, normalizedClientId, normalizedType, toJson(payload ?? {}), createdAtMs);
+    const action = {
+      id: actionId,
+      clientId: normalizedClientId,
+      type: normalizedType,
+      payload: cloneJson(payload ?? {}),
+      status: "pending",
+      createdAtMs,
+    };
+    const waiter = this.clientActionWaiters.get(normalizedClientId);
+    if (waiter) {
+      this.clientActionWaiters.delete(normalizedClientId);
+      clearTimeout(waiter.timer);
+      waiter.resolve(action);
+    }
+    return action;
+  }
+
+  async pollClientActions(clientId, { limit = 20 } = {}) {
+    const normalizedClientId = String(clientId ?? "").trim();
+    if (!normalizedClientId) {
+      return [];
+    }
+    const normalizedLimit = Math.max(1, Math.min(Number(limit) || 20, 100));
+    const rows = this._db()
+      .prepare(
+        `SELECT action_id, type, payload_json, status, created_at_ms
+           FROM client_actions
+          WHERE client_id=? AND status='pending'
+          ORDER BY created_at_ms ASC
+          LIMIT ?`,
+      )
+      .all(normalizedClientId, normalizedLimit);
+    return rows.map((row) => ({
+      id: row.action_id,
+      type: row.type,
+      payload: fromJson(row.payload_json, {}) ?? {},
+      status: row.status,
+      createdAtMs: row.created_at_ms,
+    }));
+  }
+
+  async waitForClientAction(clientId, { timeoutMs = 60_000 } = {}) {
+    const pending = await this.pollClientActions(clientId, { limit: 1 });
+    if (pending.length > 0) {
+      return pending[0];
+    }
+    const normalizedClientId = String(clientId ?? "").trim();
+    if (!normalizedClientId) {
+      return null;
+    }
+    return await new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        const active = this.clientActionWaiters.get(normalizedClientId);
+        if (active?.timer === timer) {
+          this.clientActionWaiters.delete(normalizedClientId);
+        }
+        resolve(null);
+      }, Math.max(1_000, Number(timeoutMs) || 60_000));
+      this.clientActionWaiters.set(normalizedClientId, { resolve, timer });
+    });
+  }
+
+  async ackClientAction({ clientId, actionId, status, errorText }) {
+    const normalizedClientId = String(clientId ?? "").trim();
+    const normalizedActionId = String(actionId ?? "").trim();
+    const normalizedStatus = String(status ?? "").trim().toLowerCase();
+    if (!normalizedClientId || !normalizedActionId || !normalizedStatus) {
+      throw new Error("clientId, actionId, and status are required");
+    }
+    const ackedAtMs = nowMs();
+    this._db()
+      .prepare(
+        `UPDATE client_actions
+            SET status=?,
+                acked_at_ms=?,
+                error_text=?
+          WHERE action_id=? AND client_id=?`,
+      )
+      .run(
+        normalizedStatus,
+        ackedAtMs,
+        String(errorText ?? "").trim() || null,
+        normalizedActionId,
+        normalizedClientId,
+      );
+    const result = {
+      ok: true,
+      actionId: normalizedActionId,
+      status: normalizedStatus,
+      ackedAtMs,
+    };
+    const resolutionWaiter = this.clientActionResolutionWaiters.get(normalizedActionId);
+    if (resolutionWaiter) {
+      this.clientActionResolutionWaiters.delete(normalizedActionId);
+      clearTimeout(resolutionWaiter.timer);
+      resolutionWaiter.resolve({
+        ...result,
+        errorText: String(errorText ?? "").trim() || null,
+      });
+    }
+    return result;
+  }
+
+  async waitForClientActionResolution(actionId, { timeoutMs = 20_000 } = {}) {
+    const normalizedActionId = String(actionId ?? "").trim();
+    if (!normalizedActionId) {
+      return {
+        ok: false,
+        actionId: normalizedActionId,
+        status: "error",
+        errorText: "actionId required",
+      };
+    }
+    const current = this._db()
+      .prepare(
+        `SELECT status, acked_at_ms, error_text
+           FROM client_actions
+          WHERE action_id=? LIMIT 1`,
+      )
+      .get(normalizedActionId);
+    const currentStatus = String(current?.status ?? "").trim().toLowerCase();
+    if (currentStatus && currentStatus !== "pending") {
+      return {
+        ok: currentStatus === "done",
+        actionId: normalizedActionId,
+        status: currentStatus,
+        ackedAtMs: current?.acked_at_ms ?? null,
+        errorText: String(current?.error_text ?? "").trim() || null,
+      };
+    }
+    return await new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        const active = this.clientActionResolutionWaiters.get(normalizedActionId);
+        if (active?.timer === timer) {
+          this.clientActionResolutionWaiters.delete(normalizedActionId);
+        }
+        resolve({
+          ok: false,
+          actionId: normalizedActionId,
+          status: "timeout",
+          errorText: "Mobile client did not respond in time.",
+        });
+      }, Math.max(1_000, Number(timeoutMs) || 20_000));
+      this.clientActionResolutionWaiters.set(normalizedActionId, { resolve, timer });
+    });
+  }
+}