@useorgx/openclaw-plugin 0.4.4 → 0.4.6

package/dist/index.js

@@ -12,17 +12,25 @@
  */
 import { OrgXClient } from "./api.js";
 import { createHttpHandler } from "./http-handler.js";
-import { readFileSync } from "node:fs";
+import { applyOrgxAgentSuitePlan, computeOrgxAgentSuitePlan } from "./agent-suite.js";
+import { appendActivityItems } from "./activity-store.js";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { clearPersistedApiKey, loadAuthStore, resolveInstallationId, saveAuthStore, } from "./auth-store.js";
 import { clearPersistedSnapshot, readPersistedSnapshot, writePersistedSnapshot, } from "./snapshot-store.js";
 import { appendToOutbox, readOutbox, readOutboxSummary, replaceOutbox, } from "./outbox.js";
+import { getAgentContext, readAgentContexts } from "./agent-context-store.js";
+import { readAgentRuns, markAgentRunStopped } from "./agent-run-store.js";
 import { extractProgressOutboxMessage } from "./reporting/outbox-replay.js";
 import { ensureGatewayWatchdog } from "./gateway-watchdog.js";
+import { createMcpHttpHandler, } from "./mcp-http-handler.js";
+import { autoConfigureDetectedMcpClients } from "./mcp-client-setup.js";
+import { readOpenClawGatewayPort, readOpenClawSettingsSnapshot } from "./openclaw-settings.js";
 import { posthogCapture } from "./telemetry/posthog.js";
+import { readSkillPackState, refreshSkillPackState } from "./skill-pack-state.js";
 export { OrgXClient } from "./api.js";
 const DEFAULT_BASE_URL = "https://www.useorgx.com";
 const DEFAULT_DOCS_URL = "https://orgx.mintlify.site/guides/openclaw-plugin-setup";
@@ -183,6 +191,7 @@ function resolveConfig(api, input) {
         baseUrl,
         syncIntervalMs: pluginConf.syncIntervalMs ?? 300_000,
         enabled: pluginConf.enabled ?? true,
+        autoInstallAgentSuiteOnConnect: pluginConf.autoInstallAgentSuiteOnConnect ?? true,
         dashboardEnabled: pluginConf.dashboardEnabled ?? true,
         installationId: input.installationId,
         pluginVersion: resolvePluginVersion(),
@@ -265,6 +274,29 @@ function isUuid(value) {
         return false;
     return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
 }
+function inferReportingInitiativeId(input) {
+    const env = pickNonEmptyString(process.env.ORGX_INITIATIVE_ID);
+    if (isUuid(env))
+        return env;
+    const agentId = pickNonEmptyString(input.agent_id, input.agentId);
+    if (agentId) {
+        const ctx = getAgentContext(agentId);
+        const ctxInit = ctx?.initiativeId ?? undefined;
+        if (isUuid(ctxInit ?? undefined))
+            return ctxInit ?? undefined;
+    }
+    // Fall back to the most recently updated agent context with a UUID initiative id.
+    try {
+        const store = readAgentContexts();
+        const candidates = Object.values(store.agents ?? {}).filter((ctx) => isUuid(ctx?.initiativeId ?? undefined));
+        candidates.sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt));
+        const picked = candidates[0]?.initiativeId ?? undefined;
+        return isUuid(picked) ? picked : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function toReportingPhase(phase, progressPct) {
     if (progressPct === 100)
         return "completed";
@@ -360,18 +392,73 @@ export default function register(api) {
         pollIntervalMs: null,
     };
     let activePairing = null;
-    const baseApiUrl = config.baseUrl.replace(/\/+$/, "");
+    // NOTE: base URL can be updated at runtime (e.g. user edits OpenClaw config). Keep it mutable.
+    let baseApiUrl = config.baseUrl.replace(/\/+$/, "");
     const defaultReportingCorrelationId = pickNonEmptyString(process.env.ORGX_CORRELATION_ID) ??
         `openclaw-${config.installationId}`;
+    function refreshConfigFromSources(input) {
+        const allowApiKeyChanges = input?.allowApiKeyChanges !== false;
+        const previousApiKey = config.apiKey;
+        const previousBaseUrl = config.baseUrl;
+        const previousUserId = config.userId;
+        const previousDocsUrl = config.docsUrl;
+        const previousKeySource = config.apiKeySource;
+        const latestPersisted = loadAuthStore();
+        const next = resolveConfig(api, {
+            installationId: config.installationId,
+            persistedApiKey: latestPersisted?.apiKey ?? null,
+            persistedUserId: latestPersisted?.userId ?? null,
+        });
+        const nextApiKey = allowApiKeyChanges ? next.apiKey : previousApiKey;
+        const nextUserId = allowApiKeyChanges ? next.userId : previousUserId;
+        const changed = nextApiKey !== previousApiKey ||
+            next.baseUrl !== previousBaseUrl ||
+            nextUserId !== previousUserId ||
+            next.docsUrl !== previousDocsUrl ||
+            next.apiKeySource !== previousKeySource;
+        if (!changed) {
+            return false;
+        }
+        if (allowApiKeyChanges) {
+            config.apiKey = nextApiKey;
+            config.userId = nextUserId;
+            config.apiKeySource = next.apiKeySource;
+        }
+        config.baseUrl = next.baseUrl;
+        config.docsUrl = next.docsUrl;
+        baseApiUrl = config.baseUrl.replace(/\/+$/, "");
+        client.setCredentials({
+            apiKey: config.apiKey,
+            userId: config.userId,
+            baseUrl: config.baseUrl,
+        });
+        // Keep onboarding state aligned with what's actually configured (without forcing a status transition).
+        updateOnboardingState({
+            hasApiKey: Boolean(config.apiKey),
+            keySource: config.apiKeySource,
+            docsUrl: config.docsUrl,
+            installationId: config.installationId,
+        });
+        api.log?.info?.("[orgx] Config refreshed", {
+            reason: input?.reason ?? "runtime_refresh",
+            baseUrl: config.baseUrl,
+            hasApiKey: Boolean(config.apiKey),
+            apiKeySource: config.apiKeySource,
+        });
+        return true;
+    }
     function resolveReportingContext(input) {
-        const initiativeId = pickNonEmptyString(input.initiative_id, process.env.ORGX_INITIATIVE_ID);
+        let initiativeId = pickNonEmptyString(input.initiative_id, input.initiativeId, process.env.ORGX_INITIATIVE_ID);
+        if (!isUuid(initiativeId)) {
+            initiativeId = inferReportingInitiativeId(input);
+        }
         if (!initiativeId || !isUuid(initiativeId)) {
             return {
                 ok: false,
                 error: "initiative_id is required (set ORGX_INITIATIVE_ID or pass initiative_id).",
             };
         }
-        const sourceCandidate = pickNonEmptyString(input.source_client, process.env.ORGX_SOURCE_CLIENT, "openclaw");
+        const sourceCandidate = pickNonEmptyString(input.source_client, input.sourceClient, process.env.ORGX_SOURCE_CLIENT, "openclaw");
         const sourceClient = sourceCandidate === "codex" ||
             sourceCandidate === "claude-code" ||
             sourceCandidate === "api" ||
@@ -382,7 +469,10 @@ export default function register(api) {
         const runId = isUuid(runIdCandidate) ? runIdCandidate : undefined;
         const correlationId = runId
             ? undefined
-            : pickNonEmptyString(input.correlation_id, defaultReportingCorrelationId, `openclaw-${Date.now()}`);
+            : pickNonEmptyString(input.correlation_id, input.correlationId, 
+            // Legacy: some buffered payloads only stored a local `runId` which is
+            // better treated as a correlation key than a server-backed run_id.
+            input.runId, defaultReportingCorrelationId, `openclaw-${Date.now()}`);
         return {
             ok: true,
             value: {
@@ -405,6 +495,16 @@ export default function register(api) {
             return err.message;
         return typeof err === "string" ? err : "Unexpected error";
     }
+    function stableHash(value) {
+        return createHash("sha256").update(value).digest("hex");
+    }
+    function isAuthFailure(err) {
+        const message = toErrorMessage(err).toLowerCase();
+        return (message.includes("401") ||
+            message.includes("unauthorized") ||
+            message.includes("invalid_token") ||
+            message.includes("invalid api key"));
+    }
     const registerTool = api.registerTool.bind(api);
     api.registerTool = (tool, options) => {
         const toolName = tool.name;
@@ -556,22 +656,47 @@ export default function register(api) {
     }
     function buildManualKeyConnectUrl() {
         try {
-            return new URL("/settings", baseApiUrl).toString();
+            // Deep-link into the Security section where API keys live.
+            return new URL("/settings#security", baseApiUrl).toString();
         }
         catch {
-            return "https://www.useorgx.com/settings";
+            return "https://www.useorgx.com/settings#security";
         }
     }
-    async function fetchOrgxJson(method, path, body) {
+    async function fetchOrgxJson(method, path, body, options) {
         try {
-            const response = await fetch(`${baseApiUrl}${path}`, {
-                method,
-                headers: {
-                    "Content-Type": "application/json",
-                },
-                body: body ? JSON.stringify(body) : undefined,
-            });
-            const payload = (await response.json().catch(() => null));
+            const controller = new AbortController();
+            const timeoutMs = typeof options?.timeoutMs === "number" && Number.isFinite(options.timeoutMs)
+                ? Math.max(1_000, Math.floor(options.timeoutMs))
+                : 12_000;
+            const timeout = setTimeout(() => controller.abort(), timeoutMs);
+            let response;
+            let rawText = "";
+            try {
+                response = await fetch(`${baseApiUrl}${path}`, {
+                    method,
+                    signal: controller.signal,
+                    headers: {
+                        Accept: "application/json",
+                        "Content-Type": "application/json",
+                    },
+                    body: body ? JSON.stringify(body) : undefined,
+                });
+                rawText = await response.text().catch(() => "");
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+            const payload = (() => {
+                if (!rawText)
+                    return null;
+                try {
+                    return JSON.parse(rawText);
+                }
+                catch {
+                    return null;
+                }
+            })();
             if (!response.ok) {
                 const rawError = payload?.error ?? payload?.message;
                 let errorMessage;
@@ -584,18 +709,62 @@ export default function register(api) {
                     typeof rawError.message === "string") {
                     errorMessage = rawError.message;
                 }
+                else if (rawText && rawText.trim().length > 0) {
+                    // Avoid dumping HTML (Cloudflare / Next.js error pages) into UI; keep it short.
+                    const sanitized = rawText
+                        .replace(/\s+/g, " ")
+                        .replace(/<[^>]+>/g, "")
+                        .trim();
+                    errorMessage = sanitized.length > 0 ? sanitized.slice(0, 180) : `OrgX request failed (${response.status})`;
+                }
                 else {
                     errorMessage = `OrgX request failed (${response.status})`;
                 }
-                return { ok: false, status: response.status, error: errorMessage };
+                const statusToken = `HTTP ${response.status}`;
+                if (response.status &&
+                    !errorMessage.toLowerCase().includes(statusToken.toLowerCase()) &&
+                    !errorMessage.includes(`(${response.status})`)) {
+                    errorMessage = `${errorMessage} (HTTP ${response.status})`;
+                }
+                const debugParts = [];
+                const requestId = response.headers.get("x-request-id");
+                const vercelId = response.headers.get("x-vercel-id");
+                const cfRay = response.headers.get("cf-ray");
+                const clerkStatus = response.headers.get("x-clerk-auth-status");
+                const clerkReason = response.headers.get("x-clerk-auth-reason");
+                if (requestId)
+                    debugParts.push(`req=${requestId}`);
+                if (vercelId && vercelId !== requestId)
+                    debugParts.push(`vercel=${vercelId}`);
+                if (cfRay)
+                    debugParts.push(`cf-ray=${cfRay}`);
+                if (clerkStatus)
+                    debugParts.push(`clerk=${clerkStatus}`);
+                if (clerkReason)
+                    debugParts.push(`clerk_reason=${clerkReason}`);
+                const debugSuffix = debugParts.length > 0 ? ` (${debugParts.join(", ")})` : "";
+                return {
+                    ok: false,
+                    status: response.status,
+                    error: `${errorMessage}${debugSuffix}`,
+                };
             }
             if (payload?.data !== undefined) {
                 return { ok: true, data: payload.data };
             }
-            return { ok: true, data: payload };
+            if (payload !== null) {
+                return { ok: true, data: payload };
+            }
+            return { ok: true, data: rawText };
         }
         catch (err) {
-            return { ok: false, status: 0, error: toErrorMessage(err) };
+            const message = err &&
+                typeof err === "object" &&
+                "name" in err &&
+                err.name === "AbortError"
+                ? `OrgX request timed out (method=${method}, path=${path})`
+                : toErrorMessage(err);
+            return { ok: false, status: 0, error: message };
         }
     }
     function setRuntimeApiKey(input) {
@@ -622,6 +791,23 @@ export default function register(api) {
             installationId: config.installationId,
             workspaceName: input.workspaceName ?? onboardingState.workspaceName,
         });
+        if (input.source === "browser_pairing" &&
+            process.env.ORGX_DISABLE_MCP_CLIENT_AUTOCONFIG !== "1") {
+            try {
+                const snapshot = readOpenClawSettingsSnapshot();
+                const port = readOpenClawGatewayPort(snapshot.raw);
+                const localMcpUrl = `http://127.0.0.1:${port}/orgx/mcp`;
+                void autoConfigureDetectedMcpClients({
+                    localMcpUrl,
+                    logger: api.log ?? {},
+                }).catch(() => {
+                    // best effort
+                });
+            }
+            catch {
+                // best effort
+            }
+        }
     }
     // ---------------------------------------------------------------------------
     // 1. Background Sync Service
@@ -629,7 +815,6 @@ export default function register(api) {
     let syncTimer = null;
     let syncInFlight = null;
     let syncServiceRunning = false;
-    const outboxQueues = ["progress", "decisions", "artifacts"];
     let outboxReplayState = {
         status: "idle",
         lastReplayAttemptAt: null,
@@ -642,6 +827,7 @@ export default function register(api) {
         const probeRemote = input.probeRemote === true;
         const outbox = await readOutboxSummary();
         const checks = [];
+        refreshConfigFromSources({ reason: "health_check" });
         const hasApiKey = Boolean(config.apiKey);
         if (hasApiKey) {
             checks.push({
@@ -699,7 +885,9 @@ export default function register(api) {
             else {
                 const startedAt = Date.now();
                 try {
-                    await client.getOrgSnapshot();
+                    // Avoid probing with /api/client/sync: it's heavier than necessary and can
+                    // create false negatives during transient server slowness.
+                    await client.getBillingStatus();
                     remoteReachable = true;
                     remoteLatencyMs = Date.now() - startedAt;
                     checks.push({
@@ -794,8 +982,305 @@ export default function register(api) {
             .filter(Boolean);
         return strings.length > 0 ? strings : undefined;
     }
+    function isPidAlive(pid) {
+        if (!Number.isFinite(pid) || !pid || pid <= 0)
+            return false;
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    function toFiniteNumber(value) {
+        if (typeof value === "number" && Number.isFinite(value))
+            return value;
+        if (typeof value === "string" && value.trim().length > 0) {
+            const parsed = Number(value);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+        return null;
+    }
+    function isSafePathSegment(value) {
+        const normalized = value.trim();
+        if (!normalized || normalized === "." || normalized === "..")
+            return false;
+        if (normalized.includes("/") || normalized.includes("\\") || normalized.includes("\0")) {
+            return false;
+        }
+        if (normalized.includes(".."))
+            return false;
+        return true;
+    }
+    function parseRetroEntityType(value) {
+        if (!value)
+            return undefined;
+        switch (value) {
+            case "initiative":
+            case "workstream":
+            case "milestone":
+            case "task":
+                return value;
+            default:
+                return undefined;
+        }
+    }
+    function readOpenClawSessionSummary(input) {
+        const agentId = input.agentId.trim();
+        const sessionId = input.sessionId.trim();
+        if (!agentId || !sessionId) {
+            return { tokens: 0, costUsd: 0, hadError: false, errorMessage: null };
+        }
+        if (!isSafePathSegment(agentId) || !isSafePathSegment(sessionId)) {
+            return { tokens: 0, costUsd: 0, hadError: false, errorMessage: null };
+        }
+        const jsonlPath = join(homedir(), ".openclaw", "agents", agentId, "sessions", `${sessionId}.jsonl`);
+        try {
+            if (!existsSync(jsonlPath)) {
+                return { tokens: 0, costUsd: 0, hadError: false, errorMessage: null };
+            }
+            const raw = readFileSync(jsonlPath, "utf8");
+            const lines = raw.split("\n");
+            let tokens = 0;
+            let costUsd = 0;
+            let hadError = false;
+            let errorMessage = null;
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const evt = JSON.parse(trimmed);
+                    if (evt.type !== "message")
+                        continue;
+                    const msg = evt.message;
+                    if (!msg || typeof msg !== "object")
+                        continue;
+                    const usage = msg.usage;
+                    if (usage && typeof usage === "object") {
+                        const totalTokens = toFiniteNumber(usage.totalTokens) ??
+                            toFiniteNumber(usage.total_tokens) ??
+                            null;
+                        const inputTokens = toFiniteNumber(usage.input) ?? 0;
+                        const outputTokens = toFiniteNumber(usage.output) ?? 0;
+                        const cacheReadTokens = toFiniteNumber(usage.cacheRead) ?? 0;
+                        const cacheWriteTokens = toFiniteNumber(usage.cacheWrite) ?? 0;
+                        tokens += Math.max(0, Math.round(totalTokens ??
+                            inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens));
+                        const cost = usage.cost;
+                        const costTotal = cost ? toFiniteNumber(cost.total) : null;
+                        if (costTotal !== null) {
+                            costUsd += Math.max(0, costTotal);
+                        }
+                    }
+                    const stopReason = typeof msg.stopReason === "string" ? msg.stopReason : "";
+                    const msgError = typeof msg.errorMessage === "string" && msg.errorMessage.trim().length > 0
+                        ? msg.errorMessage.trim()
+                        : null;
+                    if (stopReason === "error" || msgError) {
+                        hadError = true;
+                        errorMessage = msgError ?? errorMessage;
+                    }
+                }
+                catch {
+                    // Ignore malformed lines.
+                }
+            }
+            return {
+                tokens,
+                costUsd: Math.round(costUsd * 10_000) / 10_000,
+                hadError,
+                errorMessage,
+            };
+        }
+        catch {
+            return { tokens: 0, costUsd: 0, hadError: false, errorMessage: null };
+        }
+    }
+    async function reconcileStoppedAgentRuns() {
+        try {
+            const store = readAgentRuns();
+            const runs = Object.values(store.runs ?? {});
+            for (const run of runs) {
+                if (!run || typeof run !== "object")
+                    continue;
+                if (run.status !== "running")
+                    continue;
+                if (!run.pid || isPidAlive(run.pid))
+                    continue;
+                const stopped = markAgentRunStopped(run.runId);
+                if (!stopped)
+                    continue;
+                const initiativeId = stopped.initiativeId?.trim() ?? "";
+                if (!initiativeId)
+                    continue;
+                const summary = readOpenClawSessionSummary({
+                    agentId: stopped.agentId,
+                    sessionId: stopped.runId,
+                });
+                const completedAt = stopped.stoppedAt ?? new Date().toISOString();
+                const success = !summary.hadError;
+                const correlationId = stopped.runId;
+                const outcomePayload = {
+                    initiative_id: initiativeId,
+                    correlation_id: correlationId,
+                    source_client: "openclaw",
+                    execution_id: `openclaw:${stopped.runId}`,
+                    execution_type: "openclaw.session",
+                    agent_id: stopped.agentId,
+                    task_type: stopped.taskId ?? undefined,
+                    started_at: stopped.startedAt,
+                    completed_at: completedAt,
+                    inputs: {
+                        message: stopped.message,
+                        workstream_id: stopped.workstreamId,
+                        task_id: stopped.taskId,
+                    },
+                    outputs: {
+                        had_error: summary.hadError,
+                        error_message: summary.errorMessage,
+                    },
+                    steps: [],
+                    success,
+                    human_interventions: 0,
+                    errors: summary.errorMessage ? [summary.errorMessage] : [],
+                    metadata: {
+                        provider: stopped.provider,
+                        model: stopped.model,
+                        tokens: summary.tokens,
+                        cost_usd: summary.costUsd,
+                        source: "openclaw_agent_run_reconcile",
+                    },
+                };
+                const retroEntityType = stopped.taskId
+                    ? "task"
+                    : "initiative";
+                const retroEntityId = stopped.taskId ?? initiativeId;
+                const retroSummary = stopped.taskId
+                    ? `OpenClaw ${success ? "completed" : "blocked"} task ${stopped.taskId}.`
+                    : `OpenClaw run ${success ? "completed" : "blocked"} (session ${stopped.runId}).`;
+                const retroPayload = {
+                    initiative_id: initiativeId,
+                    correlation_id: correlationId,
+                    source_client: "openclaw",
+                    entity_type: retroEntityType,
+                    entity_id: retroEntityId,
+                    title: stopped.taskId ?? stopped.runId,
+                    idempotency_key: `retro:${stopped.runId}`,
+                    retro: {
+                        summary: retroSummary,
+                        what_went_well: success ? ["Completed without runtime error."] : [],
+                        what_went_wrong: success
+                            ? []
+                            : [summary.errorMessage ?? "Session ended with error."],
+                        decisions: [],
+                        follow_ups: success
+                            ? []
+                            : [
+                                {
+                                    title: "Investigate OpenClaw session failure and unblock task",
+                                    priority: "p0",
+                                    reason: summary.errorMessage ?? "Session ended with error.",
+                                },
+                            ],
+                        signals: {
+                            tokens: summary.tokens,
+                            cost_usd: summary.costUsd,
+                            had_error: summary.hadError,
+                            error_message: summary.errorMessage,
+                            session_id: stopped.runId,
+                            task_id: stopped.taskId,
+                            workstream_id: stopped.workstreamId,
+                            provider: stopped.provider,
+                            model: stopped.model,
+                            source: "openclaw_agent_run_reconcile",
+                        },
+                    },
+                };
+                try {
+                    await client.recordRunOutcome(outcomePayload);
+                }
+                catch (err) {
+                    const timestamp = new Date().toISOString();
+                    const activityItem = {
+                        id: randomUUID(),
+                        type: "run_completed",
+                        title: `Buffered outcome for session ${stopped.runId}`,
+                        description: null,
+                        agentId: stopped.agentId,
+                        agentName: null,
+                        runId: stopped.runId,
+                        initiativeId,
+                        timestamp,
+                        phase: success ? "completed" : "blocked",
+                        summary: retroSummary,
+                        metadata: {
+                            source: "openclaw_local_fallback",
+                            error: toErrorMessage(err),
+                        },
+                    };
+                    await appendToOutbox(initiativeId, {
+                        id: randomUUID(),
+                        type: "outcome",
+                        timestamp,
+                        payload: outcomePayload,
+                        activityItem,
+                    });
+                }
+                try {
+                    await client.recordRunRetro(retroPayload);
+                }
+                catch (err) {
+                    const timestamp = new Date().toISOString();
+                    const activityItem = {
+                        id: randomUUID(),
+                        type: "artifact_created",
+                        title: `Buffered retro for session ${stopped.runId}`,
+                        description: null,
+                        agentId: stopped.agentId,
+                        agentName: null,
+                        runId: stopped.runId,
+                        initiativeId,
+                        timestamp,
+                        phase: success ? "completed" : "blocked",
+                        summary: retroSummary,
+                        metadata: {
+                            source: "openclaw_local_fallback",
+                            error: toErrorMessage(err),
+                        },
+                    };
+                    await appendToOutbox(initiativeId, {
+                        id: randomUUID(),
+                        type: "retro",
+                        timestamp,
+                        payload: retroPayload,
+                        activityItem,
+                    });
+                }
+            }
+        }
+        catch {
+            // best effort
+        }
+    }
     async function replayOutboxEvent(event) {
         const payload = event.payload ?? {};
+        function normalizeRunFields(context) {
+            // We prefer correlation IDs for replay because many local adapters use UUID-like
+            // session IDs that do *not* exist as server-side run IDs.
+            if (context.correlationId) {
+                return { run_id: undefined, correlation_id: context.correlationId };
+            }
+            if (context.runId) {
+                return {
+                    run_id: undefined,
+                    correlation_id: `openclaw_run_${stableHash(context.runId).slice(0, 24)}`,
+                };
+            }
+            return { run_id: undefined, correlation_id: undefined };
+        }
         if (event.type === "progress") {
             const message = extractProgressOutboxMessage(payload);
             if (!message) {
@@ -809,7 +1294,11 @@ export default function register(api) {
                 throw new Error(context.error);
             }
             const rawPhase = pickStringField(payload, "phase") ?? "implementing";
-            const progressPct = typeof payload.progress_pct === "number" ? payload.progress_pct : undefined;
+            const progressPct = typeof payload.progress_pct === "number"
+                ? payload.progress_pct
+                : typeof payload.progressPct === "number"
+                    ? payload.progressPct
+                    : undefined;
             const phase = rawPhase === "intent" ||
                 rawPhase === "execution" ||
                 rawPhase === "blocked" ||
@@ -818,7 +1307,16 @@ export default function register(api) {
                 rawPhase === "completed"
                 ? rawPhase
                 : toReportingPhase(rawPhase, progressPct);
-            await client.emitActivity({
+            const metaRaw = payload.metadata;
+            const meta = metaRaw && typeof metaRaw === "object" && !Array.isArray(metaRaw)
+                ? metaRaw
+                : {};
+            const baseMetadata = {
+                ...meta,
+                source: "orgx_openclaw_outbox_replay",
+                outbox_event_id: event.id,
+            };
+            let emitPayload = {
                 initiative_id: context.value.initiativeId,
                 run_id: context.value.runId,
                 correlation_id: context.value.correlationId,
@@ -827,12 +1325,53 @@ export default function register(api) {
                 phase,
                 progress_pct: progressPct,
                 level: pickStringField(payload, "level"),
-                next_step: pickStringField(payload, "next_step") ?? undefined,
-                metadata: {
-                    source: "orgx_openclaw_outbox_replay",
-                    outbox_event_id: event.id,
-                },
-            });
+                next_step: pickStringField(payload, "next_step") ??
+                    pickStringField(payload, "nextStep") ??
+                    undefined,
+                metadata: baseMetadata,
+            };
+            // Locally-buffered progress events often store a local UUID in run_id. OrgX may reject
+            // unknown run IDs on replay; prefer a deterministic non-UUID correlation key instead.
+            if (emitPayload.run_id && !emitPayload.correlation_id) {
+                const replayCorrelationId = `openclaw_run_${stableHash(emitPayload.run_id).slice(0, 24)}`;
+                emitPayload = {
+                    ...emitPayload,
+                    run_id: undefined,
+                    correlation_id: replayCorrelationId,
+                    metadata: {
+                        ...(emitPayload.metadata ?? {}),
+                        replay_run_id_as_correlation: true,
+                    },
+                };
+            }
+            try {
+                await client.emitActivity(emitPayload);
+            }
+            catch (err) {
+                // Some locally-buffered events carry a UUID that *looks* like an OrgX run_id
+                // but was only ever used as a local correlation/grouping key. If OrgX
+                // doesn't recognize it, retry by treating it as correlation_id so OrgX can
+                // create/attach a run deterministically.
+                const msg = toErrorMessage(err);
+                if (emitPayload.run_id &&
+                    /^404\\b/.test(msg) &&
+                    /\\brun\\b/i.test(msg) &&
+                    /not found/i.test(msg)) {
+                    const replayCorrelationId = `openclaw_run_${stableHash(emitPayload.run_id).slice(0, 24)}`;
+                    await client.emitActivity({
+                        ...emitPayload,
+                        run_id: undefined,
+                        correlation_id: replayCorrelationId,
+                        metadata: {
+                            ...(emitPayload.metadata ?? {}),
+                            replay_run_id_as_correlation: true,
+                        },
+                    });
+                }
+                else {
+                    throw err;
+                }
+            }
             return;
         }
         if (event.type === "decision") {
@@ -847,12 +1386,29 @@ export default function register(api) {
             if (!context.ok) {
                 throw new Error(context.error);
             }
+            const runFields = normalizeRunFields({
+                runId: context.value.runId,
+                correlationId: context.value.correlationId,
+            });
+            // Payloads should include a stable idempotency_key when enqueued, but older
+            // events may not. Derive a deterministic fallback so outbox replay won't
+            // double-create the same remote decision.
+            const fallbackKey = stableHash(JSON.stringify({
+                t: "decision",
+                initiative_id: context.value.initiativeId,
+                run_id: context.value.runId ?? null,
+                correlation_id: context.value.correlationId ?? null,
+                question,
+            })).slice(0, 24);
+            const resolvedIdempotencyKey = pickStringField(payload, "idempotency_key") ??
+                pickStringField(payload, "idempotencyKey") ??
+                `openclaw:decision:${fallbackKey}`;
             await client.applyChangeset({
                 initiative_id: context.value.initiativeId,
-                run_id: context.value.runId,
-                correlation_id: context.value.correlationId,
+                run_id: runFields.run_id,
+                correlation_id: runFields.correlation_id,
                 source_client: context.value.sourceClient,
-                idempotency_key: pickStringField(payload, "idempotency_key") ?? `decision:${event.id}`,
+                idempotency_key: resolvedIdempotencyKey,
                 operations: [
                     {
                         op: "decision.create",
@@ -871,6 +1427,10 @@ export default function register(api) {
             if (!context.ok) {
                 throw new Error(context.error);
             }
+            const runFields = normalizeRunFields({
+                runId: context.value.runId,
+                correlationId: context.value.correlationId,
+            });
             const operations = Array.isArray(payload.operations)
                 ? payload.operations
                 : [];
@@ -880,33 +1440,230 @@ export default function register(api) {
                 });
                 return;
             }
+            // Status updates are the most common offline replay payload, and `updateEntity`
+            // is the most widely supported primitive across OrgX deployments. Prefer it
+            // when the changeset contains only simple status mutations.
+            const statusOps = operations
+                .map((op) => {
+                if (!op || typeof op !== "object")
+                    return null;
+                const record = op;
+                const kind = typeof record.op === "string" ? record.op.trim() : "";
+                if (kind === "task.update") {
+                    const taskId = typeof record.task_id === "string" ? record.task_id.trim() : "";
+                    const statusRaw = typeof record.status === "string" ? record.status.trim() : "";
+                    const normalized = statusRaw.toLowerCase().replace(/\s+/g, "_");
+                    const status = normalized === "completed" || normalized === "complete" || normalized === "finished"
+                        ? "done"
+                        : normalized === "inprogress"
+                            ? "in_progress"
+                            : normalized;
+                    if (!taskId || !status)
+                        return null;
+                    return { type: "task", id: taskId, status };
+                }
+                if (kind === "milestone.update") {
+                    const milestoneId = typeof record.milestone_id === "string" ? record.milestone_id.trim() : "";
+                    const statusRaw = typeof record.status === "string" ? record.status.trim() : "";
+                    const normalized = statusRaw.toLowerCase().replace(/\s+/g, "_");
+                    const status = normalized === "done" || normalized === "complete" || normalized === "finished"
+                        ? "completed"
+                        : normalized === "inprogress"
+                            ? "in_progress"
+                            : normalized === "todo" || normalized === "not_started" || normalized === "pending"
+                                ? "planned"
+                                : normalized === "blocked" || normalized === "stuck"
+                                    ? "at_risk"
+                                    : normalized;
+                    if (!milestoneId || !status)
+                        return null;
+                    return { type: "milestone", id: milestoneId, status };
+                }
+                return null;
+            })
+                .filter((item) => Boolean(item));
+            if (statusOps.length === operations.length) {
+                for (const op of statusOps) {
+                    await client.updateEntity(op.type, op.id, { status: op.status });
+                }
+                return;
+            }
+            // Payloads should include a stable idempotency_key when enqueued, but older
+            // events may not. Derive a deterministic fallback so outbox replay won't
+            // double-create the same remote change.
+            const fallbackKey = stableHash(JSON.stringify({
+                t: "changeset",
+                initiative_id: context.value.initiativeId,
+                run_id: context.value.runId ?? null,
+                correlation_id: context.value.correlationId ?? null,
+                operations,
+            })).slice(0, 24);
+            const resolvedIdempotencyKey = pickStringField(payload, "idempotency_key") ??
+                pickStringField(payload, "idempotencyKey") ??
+                `openclaw:changeset:${fallbackKey}`;
             await client.applyChangeset({
                 initiative_id: context.value.initiativeId,
-                run_id: context.value.runId,
-                correlation_id: context.value.correlationId,
+                run_id: runFields.run_id,
+                correlation_id: runFields.correlation_id,
                 source_client: context.value.sourceClient,
-                idempotency_key: pickStringField(payload, "idempotency_key") ?? `changeset:${event.id}`,
+                idempotency_key: resolvedIdempotencyKey,
                 operations,
             });
             return;
         }
-        if (event.type === "artifact") {
-            const name = pickStringField(payload, "name");
-            if (!name) {
-                api.log?.warn?.("[orgx] Dropping invalid artifact outbox event", {
+        if (event.type === "outcome") {
+            const context = resolveReportingContext(payload);
+            if (!context.ok) {
+                throw new Error(context.error);
+            }
+            const runFields = normalizeRunFields({
+                runId: context.value.runId,
+                correlationId: context.value.correlationId,
+            });
+            const executionId = pickStringField(payload, "execution_id") ??
+                pickStringField(payload, "executionId");
+            const executionType = pickStringField(payload, "execution_type") ??
+                pickStringField(payload, "executionType");
+            const agentId = pickStringField(payload, "agent_id") ??
+                pickStringField(payload, "agentId");
+            const success = typeof payload.success === "boolean"
+                ? payload.success
+                : null;
+            if (!executionId || !executionType || !agentId || success === null) {
+                api.log?.warn?.("[orgx] Dropping invalid outcome outbox event", {
+                    eventId: event.id,
+                });
+                return;
+            }
+            const metaRaw = payload.metadata;
+            const meta = metaRaw && typeof metaRaw === "object" && !Array.isArray(metaRaw)
+                ? metaRaw
+                : {};
+            await client.recordRunOutcome({
+                initiative_id: context.value.initiativeId,
+                run_id: runFields.run_id,
+                correlation_id: runFields.correlation_id,
+                source_client: context.value.sourceClient,
+                execution_id: executionId,
+                execution_type: executionType,
+                agent_id: agentId,
+                task_type: pickStringField(payload, "task_type") ??
+                    pickStringField(payload, "taskType") ??
+                    undefined,
+                domain: pickStringField(payload, "domain") ?? undefined,
+                started_at: pickStringField(payload, "started_at") ??
+                    pickStringField(payload, "startedAt") ??
+                    undefined,
+                completed_at: pickStringField(payload, "completed_at") ??
+                    pickStringField(payload, "completedAt") ??
+                    undefined,
+                inputs: payload.inputs && typeof payload.inputs === "object"
+                    ? payload.inputs
+                    : undefined,
+                outputs: payload.outputs && typeof payload.outputs === "object"
+                    ? payload.outputs
+                    : undefined,
+                steps: Array.isArray(payload.steps)
+                    ? payload.steps
+                    : undefined,
+                success,
+                quality_score: typeof payload.quality_score === "number"
+                    ? payload.quality_score
+                    : typeof payload.qualityScore === "number"
+                        ? payload.qualityScore
+                        : undefined,
+                duration_vs_estimate: typeof payload.duration_vs_estimate === "number"
+                    ? payload.duration_vs_estimate
+                    : typeof payload.durationVsEstimate === "number"
+                        ? payload.durationVsEstimate
+                        : undefined,
+                cost_vs_budget: typeof payload.cost_vs_budget === "number"
+                    ? payload.cost_vs_budget
+                    : typeof payload.costVsBudget === "number"
+                        ? payload.costVsBudget
+                        : undefined,
+                human_interventions: typeof payload.human_interventions === "number"
+                    ? payload.human_interventions
+                    : typeof payload.humanInterventions === "number"
+                        ? payload.humanInterventions
+                        : undefined,
+                user_satisfaction: typeof payload.user_satisfaction === "number"
+                    ? payload.user_satisfaction
+                    : typeof payload.userSatisfaction === "number"
+                        ? payload.userSatisfaction
+                        : undefined,
+                errors: Array.isArray(payload.errors)
+                    ? payload.errors.filter((e) => typeof e === "string")
+                    : undefined,
+                metadata: {
+                    ...meta,
+                    source: "orgx_openclaw_outbox_replay",
+                    outbox_event_id: event.id,
+                },
+            });
+            return;
+        }
+        if (event.type === "retro") {
+            const context = resolveReportingContext(payload);
+            if (!context.ok) {
+                throw new Error(context.error);
+            }
+            const runFields = normalizeRunFields({
+                runId: context.value.runId,
+                correlationId: context.value.correlationId,
+            });
+            const retro = payload.retro && typeof payload.retro === "object" && !Array.isArray(payload.retro)
+                ? payload.retro
+                : null;
+            const summary = retro && typeof retro.summary === "string" ? retro.summary.trim() : "";
+            if (!retro || !summary) {
+                api.log?.warn?.("[orgx] Dropping invalid retro outbox event", {
                     eventId: event.id,
                 });
                 return;
             }
-            await client.createEntity("artifact", {
-                name,
-                artifact_type: pickStringField(payload, "artifact_type") ?? "other",
-                description: pickStringField(payload, "description"),
-                artifact_url: pickStringField(payload, "url"),
-                status: "active",
+            const entityTypeRaw = pickStringField(payload, "entity_type") ??
+                pickStringField(payload, "entityType");
+            const parsedEntityType = parseRetroEntityType(entityTypeRaw) ?? null;
+            // Server-side enum parity can lag behind local clients. Only attach to the
+            // entity types that are guaranteed to exist today.
+            const entityType = parsedEntityType === "initiative" || parsedEntityType === "task"
+                ? parsedEntityType
+                : null;
+            const entityIdRaw = pickStringField(payload, "entity_id") ??
+                pickStringField(payload, "entityId") ??
+                null;
+            const entityId = isUuid(entityIdRaw ?? undefined) ? entityIdRaw : null;
+            await client.recordRunRetro({
+                initiative_id: context.value.initiativeId,
+                run_id: runFields.run_id,
+                correlation_id: runFields.correlation_id,
+                source_client: context.value.sourceClient,
+                entity_type: entityType && entityId ? entityType : undefined,
+                entity_id: entityType && entityId ? entityId : undefined,
+                title: pickStringField(payload, "title") ?? undefined,
+                idempotency_key: pickStringField(payload, "idempotency_key") ??
+                    pickStringField(payload, "idempotencyKey") ??
+                    undefined,
+                retro: retro,
+                markdown: pickStringField(payload, "markdown") ?? undefined,
             });
             return;
         }
+        if (event.type === "artifact") {
+            // Artifacts are UI-level breadcrumbs and may not be supported by every
+            // OrgX deployment's `/api/entities` schema. Persist locally and drop from
+            // the outbox so progress reporting doesn't wedge on irreplayable items.
+            try {
+                if (event.activityItem) {
+                    appendActivityItems([event.activityItem]);
+                }
+            }
+            catch {
+                // best effort
+            }
+            return;
+        }
     }
     async function flushOutboxQueues() {
         const attemptAt = new Date().toISOString();
@@ -918,7 +1675,14 @@ export default function register(api) {
         };
         let hadReplayFailure = false;
         let lastReplayError = null;
-        for (const queue of outboxQueues) {
+        // Outbox files are keyed by *session id* (e.g. initiative/run correlation),
+        // not by event type.
+        const outboxSummary = await readOutboxSummary();
+        const queues = Object.entries(outboxSummary.pendingByQueue)
+            .filter(([, count]) => typeof count === "number" && count > 0)
+            .map(([queueId]) => queueId)
+            .sort();
+        for (const queue of queues) {
             const pending = await readOutbox(queue);
             if (pending.length === 0) {
                 continue;
@@ -971,6 +1735,9 @@ export default function register(api) {
             return syncInFlight;
         }
         syncInFlight = (async () => {
+            if (!config.apiKey) {
+                refreshConfigFromSources({ reason: "sync_no_api_key" });
+            }
             if (!config.apiKey) {
                 updateOnboardingState({
                     status: "idle",
@@ -981,25 +1748,123 @@ export default function register(api) {
                 return;
             }
             try {
-                updateCachedSnapshot(await client.getOrgSnapshot());
+                await reconcileStoppedAgentRuns();
+                let snapshotError = null;
+                try {
+                    updateCachedSnapshot(await client.getOrgSnapshot());
+                }
+                catch (err) {
+                    if (isAuthFailure(err)) {
+                        throw err;
+                    }
+                    snapshotError = toErrorMessage(err);
+                    api.log?.warn?.("[orgx] Snapshot sync failed (continuing)", {
+                        error: snapshotError,
+                    });
+                }
+                // Best-effort: poll the canonical OrgX SkillPack so the dashboard/install path
+                // can apply it without blocking on an on-demand fetch.
+                try {
+                    const refreshed = await refreshSkillPackState({
+                        getSkillPack: (args) => client.getSkillPack(args),
+                    });
+                    if (refreshed.changed) {
+                        void posthogCapture({
+                            event: "openclaw_skill_pack_updated",
+                            distinctId: config.installationId,
+                            properties: {
+                                plugin_version: config.pluginVersion,
+                                skill_pack_name: refreshed.state.pack?.name ?? null,
+                                skill_pack_version: refreshed.state.pack?.version ?? null,
+                                skill_pack_checksum: refreshed.state.pack?.checksum ?? null,
+                            },
+                        }).catch(() => {
+                            // best effort
+                        });
+                    }
+                }
+                catch {
+                    // best effort
+                }
+                // Best-effort: provision/update the OrgX agent suite after we've verified a working connection.
+                // This makes domain agents available immediately for launches without requiring a manual install.
+                try {
+                    if (config.autoInstallAgentSuiteOnConnect !== false) {
+                        const state = readSkillPackState();
+                        const updateAvailable = Boolean(state.remote?.checksum &&
+                            state.pack?.checksum &&
+                            state.remote.checksum !== state.pack.checksum);
+                        const plan = computeOrgxAgentSuitePlan({
+                            packVersion: config.pluginVersion || "0.0.0",
+                            skillPack: state.overrides,
+                            skillPackRemote: state.remote,
+                            skillPackPolicy: state.policy,
+                            skillPackUpdateAvailable: updateAvailable,
+                        });
+                        const hasConflicts = (plan.workspaceFiles ?? []).some((f) => f.action === "conflict");
+                        const hasWork = Boolean(plan.openclawConfigWouldUpdate) ||
+                            (plan.workspaceFiles ?? []).some((f) => f.action !== "noop");
+                        if (hasWork && !hasConflicts) {
+                            const applied = applyOrgxAgentSuitePlan({
+                                plan,
+                                dryRun: false,
+                                skillPack: state.overrides,
+                            });
+                            void applied;
+                            void posthogCapture({
+                                event: "openclaw_agent_suite_auto_install",
+                                distinctId: config.installationId,
+                                properties: {
+                                    plugin_version: (config.pluginVersion ?? "").trim() || null,
+                                    skill_pack_source: plan.skillPack?.source ?? null,
+                                    skill_pack_checksum: plan.skillPack?.checksum ?? null,
+                                    skill_pack_version: plan.skillPack?.version ?? null,
+                                    openclaw_config_updated: Boolean(plan.openclawConfigWouldUpdate),
+                                },
+                            }).catch(() => {
+                                // best effort
+                            });
+                        }
+                    }
+                }
+                catch (err) {
+                    api.log?.debug?.("[orgx] Agent suite auto-provision skipped/failed (best effort)", {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
                 updateOnboardingState({
                     status: "connected",
                     hasApiKey: true,
-                    connectionVerified: true,
-                    lastError: null,
+                    connectionVerified: snapshotError === null,
+                    lastError: snapshotError,
                     nextAction: "open_dashboard",
                 });
                 await flushOutboxQueues();
                 api.log?.debug?.("[orgx] Sync OK");
             }
             catch (err) {
+                const authFailure = isAuthFailure(err);
+                const errorMessage = authFailure
+                    ? "Unauthorized. Your OrgX key may be revoked or expired. Reconnect in browser or use API key."
+                    : toErrorMessage(err);
                 updateOnboardingState({
                     status: "error",
                     hasApiKey: true,
                     connectionVerified: false,
-                    lastError: toErrorMessage(err),
+                    lastError: errorMessage,
                     nextAction: "reconnect",
                 });
+                if (authFailure) {
+                    void posthogCapture({
+                        event: "openclaw_sync_auth_failed",
+                        distinctId: config.installationId,
+                        properties: {
+                            plugin_version: config.pluginVersion,
+                        },
+                    }).catch(() => {
+                        // best effort
+                    });
+                }
                 api.log?.warn?.(`[orgx] Sync failed: ${err instanceof Error ? err.message : err}`);
             }
         })();
@@ -1031,7 +1896,10 @@ export default function register(api) {
             openclawVersion: input.openclawVersion,
             platform: input.platform || process.platform,
             deviceName: input.deviceName,
-        });
+        }, 
+        // Pairing can hit a cold serverless boot + supabase insert + rate-limit checks.
+        // Give it more headroom than typical lightweight API calls.
+        { timeoutMs: 30_000 });
         if (!started.ok) {
             if (isAuthRequiredError(started)) {
                 clearPairingState();
@@ -1055,7 +1923,8 @@ export default function register(api) {
                     state,
                 };
             }
-            const message = `Pairing start failed: ${started.error}`;
+            const statusLabel = started.status ? ` (HTTP ${started.status})` : "";
+            const message = `Pairing start failed${statusLabel}: ${started.error}`;
             updateOnboardingState({
                 status: "error",
                 hasApiKey: Boolean(config.apiKey),
@@ -1363,8 +2232,13 @@ export default function register(api) {
     // ---------------------------------------------------------------------------
     // 2. MCP Tools (Model Context Protocol compatible)
     // ---------------------------------------------------------------------------
+    const mcpToolRegistry = new Map();
+    const registerMcpTool = (tool, options) => {
+        mcpToolRegistry.set(tool.name, tool);
+        api.registerTool(tool, options);
+    };
     // --- orgx_status ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_status",
         description: "Get current OrgX org status: active initiatives, agent states, pending decisions, active tasks.",
         parameters: {
@@ -1384,7 +2258,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_sync ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_sync",
         description: "Push/pull memory sync with OrgX. Send local memory/daily log; receive initiatives, tasks, decisions, model routing policy.",
         parameters: {
@@ -1414,7 +2288,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_delegation_preflight ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_delegation_preflight",
         description: "Run delegation preflight to score scope quality, estimate ETA/cost, and suggest a split before autonomous execution.",
         parameters: {
@@ -1465,7 +2339,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_run_action ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_run_action",
         description: "Apply a control action to a run: pause, resume, cancel, or rollback (rollback requires checkpointId).",
         parameters: {
@@ -1509,7 +2383,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_checkpoints_list ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_checkpoints_list",
         description: "List checkpoints for a run.",
         parameters: {
@@ -1534,7 +2408,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_checkpoint_restore ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_checkpoint_restore",
         description: "Restore a run to a specific checkpoint.",
         parameters: {
@@ -1573,7 +2447,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_spawn_check ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_spawn_check",
         description: "Check quality gate + get model routing before spawning a sub-agent. Returns allowed/denied, model tier, and check details.",
         parameters: {
@@ -1602,7 +2476,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_quality_score ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_quality_score",
         description: "Record a quality score (1-5) for completed agent work. Used to gate future spawns and track performance.",
         parameters: {
@@ -1640,7 +2514,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_create_entity ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_create_entity",
         description: "Create an OrgX entity (initiative, workstream, task, decision, milestone, etc.).",
         parameters: {
@@ -1725,7 +2599,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_update_entity ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_update_entity",
         description: "Update an existing OrgX entity by type and ID.",
         parameters: {
@@ -1766,7 +2640,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_list_entities ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_list_entities",
         description: "List OrgX entities of a given type with optional status filter.",
         parameters: {
@@ -1801,6 +2675,48 @@ export default function register(api) {
             }
         },
     }, { optional: true });
+    function withProvenanceMetadata(metadata) {
+        const input = metadata ?? {};
+        const out = { ...input };
+        if (out.orgx_plugin_version === undefined) {
+            out.orgx_plugin_version = (config.pluginVersion ?? "").trim() || null;
+        }
+        try {
+            const state = readSkillPackState();
+            const overrides = state.overrides;
+            if (out.skill_pack_name === undefined) {
+                out.skill_pack_name = overrides?.name ?? state.pack?.name ?? null;
+            }
+            if (out.skill_pack_version === undefined) {
+                out.skill_pack_version = overrides?.version ?? state.pack?.version ?? null;
+            }
+            if (out.skill_pack_checksum === undefined) {
+                out.skill_pack_checksum = overrides?.checksum ?? state.pack?.checksum ?? null;
+            }
+            if (out.skill_pack_source === undefined) {
+                out.skill_pack_source = overrides?.source ?? null;
+            }
+            if (out.skill_pack_etag === undefined) {
+                out.skill_pack_etag = state.etag ?? null;
+            }
+        }
+        catch {
+            // best effort
+        }
+        if (out.orgx_provenance === undefined) {
+            out.orgx_provenance = {
+                plugin_version: out.orgx_plugin_version ?? null,
+                skill_pack: {
+                    name: out.skill_pack_name ?? null,
+                    version: out.skill_pack_version ?? null,
+                    checksum: out.skill_pack_checksum ?? null,
+                    source: out.skill_pack_source ?? null,
+                    etag: out.skill_pack_etag ?? null,
+                },
+            };
+        }
+        return out;
+    }
     async function emitActivityWithFallback(source, payload) {
         if (!payload.message || payload.message.trim().length === 0) {
             return text("❌ message is required");
@@ -1821,10 +2737,10 @@ export default function register(api) {
             progress_pct: payload.progress_pct,
             level: payload.level ?? "info",
             next_step: payload.next_step,
-            metadata: {
+            metadata: withProvenanceMetadata({
                 ...(payload.metadata ?? {}),
                 source,
-            },
+            }),
         };
         const activityItem = {
             id,
@@ -1887,10 +2803,10 @@ export default function register(api) {
             timestamp: now,
             phase: "review",
             summary: `${payload.operations.length} operation${payload.operations.length === 1 ? "" : "s"}`,
-            metadata: {
+            metadata: withProvenanceMetadata({
                 source,
                 idempotency_key: idempotencyKey,
-            },
+            }),
         };
         try {
             const result = await client.applyChangeset(requestPayload);
@@ -1908,7 +2824,7 @@ export default function register(api) {
         }
     }
     // --- orgx_emit_activity ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_emit_activity",
         description: "Emit append-only OrgX activity telemetry (launch reporting contract primary write tool).",
         parameters: {
@@ -1968,7 +2884,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_apply_changeset ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_apply_changeset",
         description: "Apply an idempotent transactional OrgX changeset (launch reporting contract primary mutation tool).",
         parameters: {
@@ -2011,7 +2927,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_report_progress (alias -> orgx_emit_activity) ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_report_progress",
         description: "Alias for orgx_emit_activity. Report progress at key milestones so the team can track your work.",
         parameters: {
@@ -2074,7 +2990,7 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_request_decision (alias -> orgx_apply_changeset decision.create) ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_request_decision",
         description: "Alias for orgx_apply_changeset with decision.create. Request a human decision before proceeding.",
         parameters: {
@@ -2159,12 +3075,16 @@ export default function register(api) {
         },
     }, { optional: true });
     // --- orgx_register_artifact ---
-    api.registerTool({
+    registerMcpTool({
         name: "orgx_register_artifact",
         description: "Register a work output (PR, document, config change, report, etc.) with OrgX. Makes it visible in the dashboard.",
         parameters: {
             type: "object",
             properties: {
+                initiative_id: {
+                    type: "string",
+                    description: "Optional initiative UUID to attach this artifact to",
+                },
                 name: {
                     type: "string",
                     description: "Human-readable artifact name (e.g., 'PR #107: Fix build size')",
@@ -2189,6 +3109,9 @@ export default function register(api) {
         async execute(_callId, params = { name: "", artifact_type: "other" }) {
             const now = new Date().toISOString();
             const id = `artifact:${randomUUID().slice(0, 8)}`;
+            const initiativeId = isUuid(params.initiative_id)
+                ? params.initiative_id
+                : inferReportingInitiativeId(params) ?? null;
             const activityItem = {
                 id,
                 type: "artifact_created",
@@ -2197,20 +3120,21 @@ export default function register(api) {
                 agentId: null,
                 agentName: null,
                 runId: null,
-                initiativeId: null,
+                initiativeId,
                 timestamp: now,
                 summary: params.url ?? null,
-                metadata: {
+                metadata: withProvenanceMetadata({
                     source: "orgx_register_artifact",
                     artifact_type: params.artifact_type,
                     url: params.url,
-                },
+                }),
             };
             try {
                 const entity = await client.createEntity("artifact", {
-                    name: params.name,
+                    title: params.name,
                     artifact_type: params.artifact_type,
-                    description: params.description,
+                    summary: params.description,
+                    initiative_id: initiativeId ?? undefined,
                     artifact_url: params.url,
                     status: "active",
                 });
@@ -2221,7 +3145,10 @@ export default function register(api) {
                     id,
                     type: "artifact",
                     timestamp: now,
-                    payload: params,
+                    payload: {
+                        ...params,
+                        initiative_id: initiativeId,
+                    },
                     activityItem,
                 });
                 return text(`Artifact saved locally: ${params.name} [${params.artifact_type}] (will sync when connected)`);
@@ -2332,7 +3259,39 @@ export default function register(api) {
     }, {
         getHealth: async (input = {}) => buildHealthReport({ probeRemote: input.probeRemote === true }),
     });
-    api.registerHttpHandler(httpHandler);
+    const mcpPromptRegistry = new Map();
+    mcpPromptRegistry.set("ship", {
+        name: "ship",
+        description: "Commit local changes, open a PR, and merge it (GitHub CLI required).",
+        arguments: [],
+        messages: [
+            {
+                role: "user",
+                content: [
+                    "Ship the current work:",
+                    "- Inspect `git status -sb` and `git diff --stat` and summarize what will be shipped.",
+                    "- Run `npm run typecheck`, `npm run test:hooks`, and `npm run build` (fix failures).",
+                    "- Create a feature branch if on `main`.",
+                    "- Commit with a clear message (do not include secrets).",
+                    "- Push branch, open a PR (use `gh pr create`), then merge it (use `gh pr merge --merge --auto`).",
+                    "- If `gh` is not authenticated, stop and tell me what to run.",
+                ].join("\n"),
+            },
+        ],
+    });
+    const mcpHttpHandler = createMcpHttpHandler({
+        tools: mcpToolRegistry,
+        prompts: mcpPromptRegistry,
+        logger: api.log ?? {},
+        serverName: "@useorgx/openclaw-plugin",
+        serverVersion: config.pluginVersion,
+    });
+    const compositeHttpHandler = async (req, res) => {
+        if (await mcpHttpHandler(req, res))
+            return true;
+        return await httpHandler(req, res);
+    };
+    api.registerHttpHandler(compositeHttpHandler);
     api.log?.info?.("[orgx] Plugin registered", {
         baseUrl: config.baseUrl,
         hasApiKey: !!config.apiKey,