@useorgx/openclaw-plugin 0.4.8 → 0.4.9

package/dist/cli/orgx.d.ts

@@ -0,0 +1,66 @@
+import type { OrgXClient } from "../api.js";
+import type { OnboardingState, OrgSnapshot } from "../types.js";
+import type { ResolvedConfig } from "../config/resolution.js";
+type DoctorCheckStatus = "pass" | "warn" | "fail";
+type ReplayStatus = "idle" | "running" | "success" | "error";
+interface DoctorCheck {
+    id: string;
+    status: DoctorCheckStatus;
+    message: string;
+}
+export interface HealthReport {
+    ok: boolean;
+    status: "ok" | "degraded" | "error";
+    generatedAt: string;
+    checks: DoctorCheck[];
+    plugin: {
+        version: string;
+        installationId: string;
+        enabled: boolean;
+        dashboardEnabled: boolean;
+        baseUrl: string;
+    };
+    auth: {
+        hasApiKey: boolean;
+        keySource: ResolvedConfig["apiKeySource"];
+        userIdConfigured: boolean;
+        onboardingStatus: OnboardingState["status"];
+    };
+    sync: {
+        serviceRunning: boolean;
+        inFlight: boolean;
+        lastSnapshotAt: string | null;
+    };
+    outbox: {
+        pendingTotal: number;
+        pendingByQueue: Record<string, number>;
+        oldestEventAt: string | null;
+        newestEventAt: string | null;
+        replayStatus: ReplayStatus;
+        lastReplayAttemptAt: string | null;
+        lastReplaySuccessAt: string | null;
+        lastReplayFailureAt: string | null;
+        lastReplayError: string | null;
+    };
+    remote: {
+        enabled: boolean;
+        reachable: boolean | null;
+        latencyMs: number | null;
+        error: string | null;
+    };
+}
+export interface RegisterOrgxCliDeps {
+    registerCli: (fn: (ctx: {
+        program: any;
+    }) => void, options?: {
+        commands?: string[];
+    }) => void;
+    client: OrgXClient;
+    formatSnapshot: (snapshot: OrgSnapshot) => string;
+    buildHealthReport: (input?: {
+        probeRemote?: boolean;
+    }) => Promise<HealthReport>;
+    apiKeySourceLabel: (source: ResolvedConfig["apiKeySource"]) => string;
+}
+export declare function registerOrgxCli(deps: RegisterOrgxCliDeps): void;
+export {};

package/dist/cli/orgx.js

@@ -0,0 +1,91 @@
+export function registerOrgxCli(deps) {
+    deps.registerCli(({ program }) => {
+        const cmd = program.command("orgx").description("OrgX integration commands");
+        cmd
+            .command("status")
+            .description("Show current OrgX org status")
+            .action(async () => {
+            try {
+                const snap = await deps.client.getOrgSnapshot();
+                console.log(deps.formatSnapshot(snap));
+            }
+            catch (err) {
+                console.error(`Error: ${err instanceof Error ? err.message : err}`);
+                process.exit(1);
+            }
+        });
+        cmd
+            .command("sync")
+            .description("Trigger manual memory sync")
+            .option("--memory <text>", "Memory to push")
+            .option("--daily-log <text>", "Daily log to push")
+            .action(async (opts = {}) => {
+            try {
+                const resp = await deps.client.syncMemory({
+                    memory: opts.memory,
+                    dailyLog: opts.dailyLog,
+                });
+                console.log("Sync complete:");
+                console.log(`  Initiatives: ${resp.initiatives?.length ?? 0}`);
+                console.log(`  Active tasks: ${resp.activeTasks?.length ?? 0}`);
+                console.log(`  Pending decisions: ${resp.pendingDecisions?.length ?? 0}`);
+            }
+            catch (err) {
+                console.error(`Sync failed: ${err instanceof Error ? err.message : err}`);
+                process.exit(1);
+            }
+        });
+        cmd
+            .command("doctor")
+            .description("Run plugin diagnostics and connectivity checks")
+            .option("--json", "Print the report as JSON")
+            .option("--no-remote", "Skip remote OrgX API reachability probe")
+            .action(async (opts = {}) => {
+            try {
+                const report = await deps.buildHealthReport({
+                    probeRemote: opts.remote !== false,
+                });
+                if (opts.json) {
+                    console.log(JSON.stringify(report, null, 2));
+                    if (!report.ok)
+                        process.exit(1);
+                    return;
+                }
+                console.log("OrgX Doctor");
+                console.log(`  Status: ${report.status.toUpperCase()}`);
+                console.log(`  Plugin: v${report.plugin.version}`);
+                console.log(`  Base URL: ${report.plugin.baseUrl}`);
+                console.log(`  API Key Source: ${deps.apiKeySourceLabel(report.auth.keySource)}`);
+                console.log(`  Outbox Pending: ${report.outbox.pendingTotal}`);
+                console.log("");
+                console.log("Checks:");
+                for (const check of report.checks) {
+                    const prefix = check.status === "pass"
+                        ? "[PASS]"
+                        : check.status === "warn"
+                            ? "[WARN]"
+                            : "[FAIL]";
+                    console.log(`  ${prefix} ${check.message}`);
+                }
+                if (report.remote.enabled) {
+                    if (report.remote.reachable === true) {
+                        console.log(`  Remote probe latency: ${report.remote.latencyMs ?? "?"}ms`);
+                    }
+                    else if (report.remote.reachable === false) {
+                        console.log(`  Remote probe error: ${report.remote.error ?? "Unknown error"}`);
+                    }
+                    else {
+                        console.log("  Remote probe: skipped");
+                    }
+                }
+                if (!report.ok) {
+                    process.exit(1);
+                }
+            }
+            catch (err) {
+                console.error(`Doctor failed: ${err instanceof Error ? err.message : err}`);
+                process.exit(1);
+            }
+        });
+    }, { commands: ["orgx"] });
+}

package/dist/config/refresh.d.ts

@@ -0,0 +1,32 @@
+import type { OnboardingState } from "../types.js";
+import type { PluginApiLike, ResolvedConfig } from "./resolution.js";
+type AuthStoreState = {
+    apiKey?: string | null;
+    userId?: string | null;
+} | null;
+type RefreshInput = {
+    reason?: string;
+    allowApiKeyChanges?: boolean;
+};
+type RefreshDeps = {
+    api: PluginApiLike;
+    config: ResolvedConfig;
+    loadAuthStore: () => AuthStoreState;
+    resolveConfig: (api: PluginApiLike, input: {
+        installationId: string;
+        persistedApiKey: string | null;
+        persistedUserId: string | null;
+    }) => ResolvedConfig;
+    updateOnboardingState: (updates: Partial<OnboardingState>) => unknown;
+    setCredentials: (input: {
+        apiKey: string;
+        userId: string;
+        baseUrl: string;
+    }) => void;
+    logInfo?: (message: string, meta?: Record<string, unknown>) => void;
+};
+export declare function refreshResolvedConfig(deps: RefreshDeps, input?: RefreshInput): {
+    changed: boolean;
+    baseApiUrl: string;
+};
+export {};

package/dist/config/refresh.js

@@ -0,0 +1,55 @@
+export function refreshResolvedConfig(deps, input) {
+    const allowApiKeyChanges = input?.allowApiKeyChanges !== false;
+    const previousApiKey = deps.config.apiKey;
+    const previousBaseUrl = deps.config.baseUrl;
+    const previousUserId = deps.config.userId;
+    const previousDocsUrl = deps.config.docsUrl;
+    const previousKeySource = deps.config.apiKeySource;
+    const latestPersisted = deps.loadAuthStore();
+    const next = deps.resolveConfig(deps.api, {
+        installationId: deps.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 {
+            changed: false,
+            baseApiUrl: deps.config.baseUrl.replace(/\/+$/, ""),
+        };
+    }
+    if (allowApiKeyChanges) {
+        deps.config.apiKey = nextApiKey;
+        deps.config.userId = nextUserId;
+        deps.config.apiKeySource = next.apiKeySource;
+    }
+    deps.config.baseUrl = next.baseUrl;
+    deps.config.docsUrl = next.docsUrl;
+    deps.setCredentials({
+        apiKey: deps.config.apiKey,
+        userId: deps.config.userId,
+        baseUrl: deps.config.baseUrl,
+    });
+    deps.updateOnboardingState({
+        hasApiKey: Boolean(deps.config.apiKey),
+        keySource: deps.config.apiKeySource,
+        docsUrl: deps.config.docsUrl,
+        installationId: deps.config.installationId,
+    });
+    deps.logInfo?.("[orgx] Config refreshed", {
+        reason: input?.reason ?? "runtime_refresh",
+        baseUrl: deps.config.baseUrl,
+        hasApiKey: Boolean(deps.config.apiKey),
+        apiKeySource: deps.config.apiKeySource,
+    });
+    return {
+        changed: true,
+        baseApiUrl: deps.config.baseUrl.replace(/\/+$/, ""),
+    };
+}

package/dist/config/resolution.d.ts

@@ -0,0 +1,37 @@
+import type { OrgXConfig } from "../types.js";
+export interface ResolvedConfig extends OrgXConfig {
+    dashboardEnabled: boolean;
+    installationId: string;
+    pluginVersion: string;
+    docsUrl: string;
+    apiKeySource: "config" | "environment" | "persisted" | "openclaw-config-file" | "legacy-dev" | "none";
+}
+export interface PluginApiLike {
+    config?: {
+        plugins?: {
+            entries?: {
+                orgx?: {
+                    config?: Partial<OrgXConfig & {
+                        dashboardEnabled: boolean;
+                    }>;
+                };
+            };
+        };
+    };
+}
+export declare function isUserScopedApiKey(apiKey: string): boolean;
+export declare function resolveRuntimeUserId(apiKey: string, candidates: Array<string | null | undefined>): string;
+export declare function normalizeBaseUrl(raw: string | undefined): string;
+export declare function readLegacyEnvValue(keyPattern: RegExp): string;
+export declare function readOpenClawOrgxConfig(): {
+    apiKey: string;
+    userId: string;
+    baseUrl: string;
+};
+export declare function resolvePluginVersion(): string;
+export declare function resolveDocsUrl(baseUrl: string): string;
+export declare function resolveConfig(api: PluginApiLike, input: {
+    installationId: string;
+    persistedApiKey: string | null;
+    persistedUserId: string | null;
+}): ResolvedConfig;

package/dist/config/resolution.js

@@ -0,0 +1,178 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+const DEFAULT_BASE_URL = "https://www.useorgx.com";
+const DEFAULT_DOCS_URL = "https://orgx.mintlify.site/guides/openclaw-plugin-setup";
+export function isUserScopedApiKey(apiKey) {
+    return apiKey.trim().toLowerCase().startsWith("oxk_");
+}
+export function resolveRuntimeUserId(apiKey, candidates) {
+    if (isUserScopedApiKey(apiKey)) {
+        // For oxk_ keys, the OrgX API ignores X-Orgx-User-Id, but we still keep a UUID
+        // around for created_by_id on certain entity writes (e.g., work_artifacts).
+        for (const candidate of candidates) {
+            if (typeof candidate !== "string")
+                continue;
+            const trimmed = candidate.trim();
+            if (/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(trimmed)) {
+                return trimmed;
+            }
+        }
+        return "";
+    }
+    for (const candidate of candidates) {
+        if (typeof candidate === "string") {
+            const trimmed = candidate.trim();
+            if (trimmed.length > 0)
+                return trimmed;
+        }
+    }
+    return "";
+}
+function normalizeHost(value) {
+    return value.trim().toLowerCase().replace(/^\[|\]$/g, "");
+}
+function isLoopbackHostname(hostname) {
+    const normalized = normalizeHost(hostname);
+    return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
+}
+export function normalizeBaseUrl(raw) {
+    const candidate = raw?.trim() ?? "";
+    if (!candidate) {
+        return DEFAULT_BASE_URL;
+    }
+    try {
+        const parsed = new URL(candidate);
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+            return DEFAULT_BASE_URL;
+        }
+        // Do not allow credential-bearing URLs.
+        if (parsed.username || parsed.password) {
+            return DEFAULT_BASE_URL;
+        }
+        // Plain HTTP is only allowed for local loopback development.
+        if (parsed.protocol === "http:" && !isLoopbackHostname(parsed.hostname)) {
+            return DEFAULT_BASE_URL;
+        }
+        parsed.search = "";
+        parsed.hash = "";
+        const normalizedPath = parsed.pathname.replace(/\/+$/, "");
+        parsed.pathname = normalizedPath;
+        const normalized = parsed.toString().replace(/\/+$/, "");
+        return normalized.length > 0 ? normalized : DEFAULT_BASE_URL;
+    }
+    catch {
+        return DEFAULT_BASE_URL;
+    }
+}
+export function readLegacyEnvValue(keyPattern) {
+    try {
+        const envPath = join(homedir(), "Code", "orgx", "orgx", ".env.local");
+        const envContent = readFileSync(envPath, "utf-8");
+        const match = envContent.match(keyPattern);
+        return match?.[1]?.trim() ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+export function readOpenClawOrgxConfig() {
+    try {
+        const configPath = join(homedir(), ".openclaw", "openclaw.json");
+        const raw = readFileSync(configPath, "utf8");
+        const parsed = JSON.parse(raw);
+        const plugins = parsed.plugins && typeof parsed.plugins === "object"
+            ? parsed.plugins
+            : {};
+        const entries = plugins.entries && typeof plugins.entries === "object"
+            ? plugins.entries
+            : {};
+        const orgx = entries.orgx && typeof entries.orgx === "object"
+            ? entries.orgx
+            : {};
+        const config = orgx.config && typeof orgx.config === "object"
+            ? orgx.config
+            : {};
+        const apiKey = typeof config.apiKey === "string" ? config.apiKey.trim() : "";
+        const userId = typeof config.userId === "string" ? config.userId.trim() : "";
+        const baseUrl = typeof config.baseUrl === "string" ? config.baseUrl.trim() : "";
+        return { apiKey, userId, baseUrl };
+    }
+    catch {
+        return { apiKey: "", userId: "", baseUrl: "" };
+    }
+}
+function resolveApiKey(pluginConf, persistedApiKey) {
+    if (pluginConf.apiKey && pluginConf.apiKey.trim().length > 0) {
+        return { value: pluginConf.apiKey.trim(), source: "config" };
+    }
+    if (process.env.ORGX_API_KEY && process.env.ORGX_API_KEY.trim().length > 0) {
+        return { value: process.env.ORGX_API_KEY.trim(), source: "environment" };
+    }
+    if (persistedApiKey && persistedApiKey.trim().length > 0) {
+        return { value: persistedApiKey.trim(), source: "persisted" };
+    }
+    const openclaw = readOpenClawOrgxConfig();
+    if (openclaw.apiKey) {
+        return { value: openclaw.apiKey, source: "openclaw-config-file" };
+    }
+    // For local dev convenience we read `ORGX_API_KEY` from `~/Code/orgx/orgx/.env.local`.
+    // Do not auto-consume `ORGX_SERVICE_KEY` because service keys often require `X-Orgx-User-Id`,
+    // and the dashboard/client flows are intended to run on user-scoped keys (`oxk_...`).
+    const legacy = readLegacyEnvValue(/^ORGX_API_KEY=["']?([^"'\n]+)["']?$/m);
+    if (legacy) {
+        return { value: legacy, source: "legacy-dev" };
+    }
+    return { value: "", source: "none" };
+}
+export function resolvePluginVersion() {
+    try {
+        const packagePath = fileURLToPath(new URL("../../package.json", import.meta.url));
+        const parsed = JSON.parse(readFileSync(packagePath, "utf8"));
+        return parsed.version && parsed.version.trim().length > 0 ? parsed.version : "dev";
+    }
+    catch {
+        return "dev";
+    }
+}
+export function resolveDocsUrl(baseUrl) {
+    const normalized = baseUrl.replace(/\/+$/, "");
+    try {
+        const parsed = new URL(normalized);
+        if (isLoopbackHostname(parsed.hostname)) {
+            return `${normalized}/docs/mintlify/guides/openclaw-plugin-setup`;
+        }
+    }
+    catch {
+        return DEFAULT_DOCS_URL;
+    }
+    return DEFAULT_DOCS_URL;
+}
+export function resolveConfig(api, input) {
+    const pluginConf = api.config?.plugins?.entries?.orgx?.config ?? {};
+    const openclaw = readOpenClawOrgxConfig();
+    const apiKeyResolution = resolveApiKey(pluginConf, input.persistedApiKey);
+    const apiKey = apiKeyResolution.value;
+    const userId = resolveRuntimeUserId(apiKey, [
+        pluginConf.userId,
+        process.env.ORGX_USER_ID,
+        input.persistedUserId,
+        openclaw.userId,
+        readLegacyEnvValue(/^ORGX_USER_ID=["']?([^"'\n]+)["']?$/m),
+    ]);
+    const baseUrl = normalizeBaseUrl(pluginConf.baseUrl || process.env.ORGX_BASE_URL || openclaw.baseUrl || DEFAULT_BASE_URL);
+    return {
+        apiKey,
+        userId,
+        baseUrl,
+        syncIntervalMs: pluginConf.syncIntervalMs ?? 300_000,
+        enabled: pluginConf.enabled ?? true,
+        autoInstallAgentSuiteOnConnect: pluginConf.autoInstallAgentSuiteOnConnect ?? true,
+        dashboardEnabled: pluginConf.dashboardEnabled ?? true,
+        installationId: input.installationId,
+        pluginVersion: resolvePluginVersion(),
+        docsUrl: resolveDocsUrl(baseUrl),
+        apiKeySource: apiKeyResolution.source,
+    };
+}

package/dist/contracts/shared-types.d.ts

@@ -0,0 +1,147 @@
+export type OnboardingStatus = 'idle' | 'starting' | 'awaiting_browser_auth' | 'pairing' | 'connected' | 'error' | 'manual_key';
+export type OnboardingNextAction = 'connect' | 'wait_for_browser' | 'open_dashboard' | 'retry' | 'start_pairing' | 'open_browser' | 'poll' | 'enter_manual_key' | 'reconnect' | 'none';
+export type OnboardingKeySource = 'config' | 'environment' | 'persisted' | 'openclaw-config-file' | 'legacy-dev' | 'none';
+export interface OnboardingState {
+    status: OnboardingStatus;
+    hasApiKey: boolean;
+    connectionVerified: boolean;
+    workspaceName: string | null;
+    lastError: string | null;
+    nextAction: OnboardingNextAction;
+    docsUrl: string;
+    keySource?: OnboardingKeySource;
+    installationId?: string | null;
+    connectUrl: string | null;
+    pairingId?: string | null;
+    expiresAt: string | null;
+    pollIntervalMs: number | null;
+}
+export type RunPhase = 'intent' | 'execution' | 'blocked' | 'review' | 'handoff' | 'completed';
+export type RuntimeSourceClient = 'openclaw' | 'codex' | 'claude-code' | 'api' | 'unknown';
+export type RuntimeProviderLogo = 'codex' | 'openai' | 'anthropic' | 'openclaw' | 'orgx' | 'unknown';
+export type RuntimeInstanceState = 'active' | 'stale' | 'stopped' | 'error';
+export interface RuntimeInstance {
+    id: string;
+    sourceClient: RuntimeSourceClient;
+    displayName: string;
+    providerLogo: RuntimeProviderLogo;
+    state: RuntimeInstanceState;
+    runId: string | null;
+    correlationId: string | null;
+    initiativeId: string | null;
+    workstreamId: string | null;
+    taskId: string | null;
+    agentId: string | null;
+    agentName: string | null;
+    phase: string | null;
+    progressPct: number | null;
+    currentTask: string | null;
+    lastHeartbeatAt: string | null;
+    lastEventAt: string;
+    lastMessage: string | null;
+    metadata: Record<string, unknown> | null;
+}
+export type LiveActivityType = 'run_started' | 'run_completed' | 'run_failed' | 'artifact_created' | 'decision_requested' | 'decision_resolved' | 'handoff_requested' | 'handoff_claimed' | 'handoff_fulfilled' | 'blocker_created' | 'milestone_completed' | 'delegation';
+export interface LiveActivityItem {
+    id: string;
+    type: LiveActivityType;
+    title: string;
+    description: string | null;
+    agentId: string | null;
+    agentName: string | null;
+    requesterAgentId: string | null;
+    requesterAgentName: string | null;
+    executorAgentId: string | null;
+    executorAgentName: string | null;
+    runId: string | null;
+    initiativeId: string | null;
+    timestamp: string;
+    phase?: RunPhase | null;
+    state?: string | null;
+    kind?: string | null;
+    summary?: string | null;
+    decisionRequired?: boolean;
+    costDelta?: number | null;
+    runtimeClient?: RuntimeSourceClient | null;
+    runtimeLabel?: string | null;
+    runtimeProvider?: RuntimeProviderLogo | null;
+    instanceId?: string | null;
+    lastHeartbeatAt?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface LiveDecision {
+    id: string;
+    title: string;
+    context: string | null;
+    status: string;
+    agentName: string | null;
+    requestedAt: string | null;
+    updatedAt: string | null;
+    waitingMinutes: number;
+    metadata?: Record<string, unknown>;
+}
+export interface SessionTreeNode {
+    id: string;
+    parentId: string | null;
+    runId: string;
+    title: string;
+    agentId: string | null;
+    agentName: string | null;
+    status: string;
+    progress: number | null;
+    initiativeId: string | null;
+    workstreamId: string | null;
+    groupId: string;
+    groupLabel: string;
+    startedAt: string | null;
+    updatedAt: string | null;
+    lastEventAt: string | null;
+    lastEventSummary: string | null;
+    blockers: string[];
+    phase?: RunPhase | null;
+    state?: string | null;
+    eta?: string | null;
+    cost?: number | null;
+    checkpointCount?: number | null;
+    blockerReason?: string | null;
+    runtimeClient?: RuntimeSourceClient | null;
+    runtimeLabel?: string | null;
+    runtimeProvider?: RuntimeProviderLogo | null;
+    instanceId?: string | null;
+    lastHeartbeatAt?: string | null;
+}
+export interface SessionTreeEdge {
+    parentId: string;
+    childId: string;
+}
+export interface SessionTreeGroup {
+    id: string;
+    label: string;
+    status: string | null;
+}
+export interface SessionTreeResponse {
+    nodes: SessionTreeNode[];
+    edges: SessionTreeEdge[];
+    groups: SessionTreeGroup[];
+}
+export interface HandoffEvent {
+    id: string;
+    handoffId: string;
+    eventType: string;
+    actorType: string | null;
+    actorId: string | null;
+    payload: Record<string, unknown> | null;
+    createdAt: string;
+}
+export interface HandoffSummary {
+    id: string;
+    title: string;
+    status: string;
+    priority: string | null;
+    summary: string | null;
+    currentActorType: string | null;
+    currentActorId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    events: HandoffEvent[];
+}

package/dist/contracts/shared-types.js

@@ -0,0 +1,3 @@
+// Canonical shared types consumed by both core plugin code and dashboard code.
+// Keep this file dependency-free so it can be imported across build boundaries.
+export {};