@useorgx/openclaw-plugin 0.4.8 → 0.7.0

package/dist/cli/orgx.js

@@ -0,0 +1,102 @@
+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")
+            .option("--agents-json <json>", "JSON array of local agent states to include (id,name,domain,status)")
+            .action(async (opts = {}) => {
+            try {
+                let agents;
+                if (typeof opts.agentsJson === "string" && opts.agentsJson.trim().length > 0) {
+                    const parsed = JSON.parse(opts.agentsJson);
+                    if (!Array.isArray(parsed)) {
+                        throw new Error("--agents-json must be a JSON array");
+                    }
+                    agents = parsed;
+                }
+                const resp = await deps.client.syncMemory({
+                    memory: opts.memory,
+                    dailyLog: opts.dailyLog,
+                    agents,
+                });
+                console.log("Sync complete:");
+                console.log(`  Initiatives: ${resp.initiatives?.length ?? 0}`);
+                console.log(`  Agents: ${resp.agents?.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/client.d.ts

@@ -6,7 +6,7 @@
  *
  * Uses native fetch — no external dependencies.
  */
-import type { OrgSnapshot, SyncPayload, SyncResponse, SpawnGuardResult, QualityScore, Entity, EntityListFilters, EmitActivityRequest, EmitActivityResponse, ApplyChangesetRequest, ApplyChangesetResponse, RecordRunOutcomeRequest, RecordRunOutcomeResponse, RecordRunRetroRequest, RecordRunRetroResponse, LiveActivityItem, SessionTreeResponse, HandoffSummary, CheckpointSummary, RestoreRequest, DelegationPreflightResult, BillingStatus, BillingCheckoutRequest, BillingUrlResult, KickoffContextRequest, KickoffContextResponse, SkillPack } from "./types.js";
+import type { OrgSnapshot, SyncPayload, SyncResponse, SpawnGuardResult, QualityScore, Entity, EntityListFilters, EmitActivityRequest, EmitActivityResponse, ApplyChangesetRequest, ApplyChangesetResponse, RecordRunOutcomeRequest, RecordRunOutcomeResponse, RecordRunRetroRequest, RecordRunRetroResponse, LiveActivityItem, SessionTreeResponse, HandoffSummary, EntityUpdateResult, CheckpointSummary, RestoreRequest, DelegationPreflightResult, BillingStatus, BillingCheckoutRequest, BillingUrlResult, UsageControlPlaneSummary, KickoffContextRequest, KickoffContextResponse, SkillPack, ClientRuntimeSettingsResponse, ClientRuntimeSettingsUpdateRequest } from "./types.js";
 export type DecisionAction = "approve" | "reject";
 export type RunAction = "pause" | "resume" | "cancel" | "rollback";
 export interface DecisionActionResult {
@@ -15,6 +15,10 @@ export interface DecisionActionResult {
     entity?: Entity;
     error?: string;
 }
+export interface DecisionMutationInput {
+    note?: string;
+    optionId?: string;
+}
 export declare class OrgXClient {
     private apiKey;
     private baseUrl;
@@ -40,6 +44,7 @@ export declare class OrgXClient {
     private post;
     private patch;
     private buildQuery;
+    private unwrapSyncResponse;
     getOrgSnapshot(): Promise<OrgSnapshot>;
     syncMemory(payload: SyncPayload): Promise<SyncResponse>;
     getKickoffContext(payload: KickoffContextRequest): Promise<KickoffContextResponse>;
@@ -61,6 +66,12 @@ export declare class OrgXClient {
         status: number;
         error: string;
     }>;
+    getClientAgentRuntimeSettings(input?: {
+        workspaceId?: string | null;
+        /** Legacy alias retained for backward compatibility */
+        projectId?: string | null;
+    }): Promise<ClientRuntimeSettingsResponse>;
+    updateClientAgentRuntimeSettings(payload: ClientRuntimeSettingsUpdateRequest): Promise<ClientRuntimeSettingsResponse>;
     delegationPreflight(payload: {
         intent: string;
         acceptanceCriteria?: string[];
@@ -84,6 +95,11 @@ export declare class OrgXClient {
      * PATCH /api/entities { type, id, ...updates }
      */
     updateEntity(type: string, id: string, updates: Record<string, unknown>): Promise<Entity>;
+    /**
+     * Update an OrgX entity and preserve reassignment metadata when present.
+     * PATCH /api/entities { type, id, ...updates }
+     */
+    updateEntityDetailed(type: string, id: string, updates: Record<string, unknown>): Promise<EntityUpdateResult>;
     /**
      * List OrgX entities.
      * GET /api/entities?type={type}&status={status}&limit={n}
@@ -98,6 +114,9 @@ export declare class OrgXClient {
     getBillingStatus(): Promise<BillingStatus>;
     createBillingCheckout(payload: BillingCheckoutRequest): Promise<BillingUrlResult>;
     createBillingPortal(): Promise<BillingUrlResult>;
+    getUsageControlPlaneSummary(): Promise<UsageControlPlaneSummary>;
+    getUsageUnified(): Promise<UsageControlPlaneSummary>;
+    getUsageForecast(): Promise<Pick<UsageControlPlaneSummary, "generatedAt" | "period" | "predicted" | "risk" | "headroom" | "utilization">>;
     emitActivity(payload: EmitActivityRequest): Promise<EmitActivityResponse>;
     applyChangeset(payload: ApplyChangesetRequest): Promise<ApplyChangesetResponse>;
     recordRunOutcome(payload: RecordRunOutcomeRequest): Promise<RecordRunOutcomeResponse>;
@@ -105,11 +124,17 @@ export declare class OrgXClient {
     getLiveSessions(params?: {
         limit?: number;
         initiative?: string | null;
+        workspaceId?: string | null;
+        /** @deprecated Use workspaceId */
+        projectId?: string | null;
     }): Promise<SessionTreeResponse>;
     getLiveActivity(params?: {
         limit?: number;
         run?: string | null;
         since?: string | null;
+        workspaceId?: string | null;
+        /** @deprecated Use workspaceId */
+        projectId?: string | null;
     }): Promise<{
         activities: LiveActivityItem[];
         total: number;
@@ -117,6 +142,9 @@ export declare class OrgXClient {
     getLiveAgents(params?: {
         initiative?: string | null;
         includeIdle?: boolean;
+        workspaceId?: string | null;
+        /** @deprecated Use workspaceId */
+        projectId?: string | null;
     }): Promise<{
         agents: unknown[];
         summary: Record<string, number>;
@@ -124,9 +152,18 @@ export declare class OrgXClient {
     getLiveInitiatives(params?: {
         id?: string | null;
         limit?: number;
+        offset?: number;
+        workspaceId?: string | null;
+        /** @deprecated Use workspaceId */
+        projectId?: string | null;
     }): Promise<{
         initiatives: unknown[];
         total: number;
+        pagination?: {
+            limit?: number;
+            offset?: number;
+            has_more?: boolean;
+        };
     }>;
     getHandoffs(): Promise<{
         handoffs: HandoffSummary[];
@@ -166,10 +203,13 @@ export declare class OrgXClient {
     getLiveDecisions(params?: {
         status?: string;
         limit?: number;
+        workspaceId?: string | null;
+        /** @deprecated Use workspaceId */
+        projectId?: string | null;
     }): Promise<{
         decisions: Entity[];
         total: number;
     }>;
-    decideDecision(id: string, action: DecisionAction, note?: string): Promise<Entity>;
-    bulkDecideDecisions(ids: string[], action: DecisionAction, note?: string): Promise<DecisionActionResult[]>;
+    decideDecision(id: string, action: DecisionAction, input?: DecisionMutationInput): Promise<Entity>;
+    bulkDecideDecisions(ids: string[], action: DecisionAction, input?: DecisionMutationInput): Promise<DecisionActionResult[]>;
 }