@useorgx/openclaw-plugin 0.4.6 → 0.4.9

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

@@ -26,6 +26,7 @@ export declare class OrgXClient {
         baseUrl?: string;
     }): void;
     getBaseUrl(): string;
+    getUserId(): string;
     /**
      * Low-level authenticated request helper.
      *

package/dist/contracts/client.js

@@ -80,17 +80,16 @@ export class OrgXClient {
     constructor(apiKey, baseUrl, userId) {
         this.apiKey = apiKey;
         this.baseUrl = normalizeClientBaseUrl(baseUrl, DEFAULT_CLIENT_BASE_URL);
-        this.userId = isUserScopedApiKey(apiKey) ? "" : userId || "";
+        // Keep userId available even for oxk_ keys (it can be used as created_by_id for certain writes),
+        // but only send it as a header for non-user-scoped keys.
+        this.userId = userId || "";
     }
     setCredentials(input) {
         if (typeof input.apiKey === "string") {
             this.apiKey = input.apiKey;
-            if (isUserScopedApiKey(this.apiKey)) {
-                this.userId = "";
-            }
         }
         if (typeof input.userId === "string") {
-            this.userId = isUserScopedApiKey(this.apiKey) ? "" : input.userId;
+            this.userId = input.userId;
         }
         if (typeof input.baseUrl === "string" && input.baseUrl.trim().length > 0) {
             this.baseUrl = normalizeClientBaseUrl(input.baseUrl, this.baseUrl);
@@ -99,6 +98,9 @@ export class OrgXClient {
     getBaseUrl() {
         return this.baseUrl;
     }
+    getUserId() {
+        return this.userId;
+    }
     // ===========================================================================
     // HTTP helpers
     // ===========================================================================

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 {};

package/dist/contracts/types.d.ts

@@ -4,6 +4,7 @@
  * Types for the plugin's API client and tool interfaces.
  * Mirrors the server-side types in orgx/lib/client-integration/types.ts
  */
+export type { HandoffEvent, HandoffSummary, LiveActivityItem, LiveActivityType, LiveDecision, OnboardingKeySource, OnboardingNextAction, OnboardingState, OnboardingStatus, RunPhase, RuntimeInstance, RuntimeInstanceState, RuntimeProviderLogo, RuntimeSourceClient, SessionTreeEdge, SessionTreeGroup, SessionTreeNode, SessionTreeResponse, } from './shared-types.js';
 export interface OrgXConfig {
     /** OrgX API key */
     apiKey: string;
@@ -24,23 +25,6 @@ export interface OrgXConfig {
      */
     autoInstallAgentSuiteOnConnect?: boolean;
 }
-export type OnboardingStatus = 'idle' | 'starting' | 'awaiting_browser_auth' | 'pairing' | 'connected' | 'error' | 'manual_key';
-export type OnboardingNextAction = 'connect' | 'wait_for_browser' | 'open_dashboard' | 'enter_manual_key' | 'retry' | 'reconnect';
-export interface OnboardingState {
-    status: OnboardingStatus;
-    hasApiKey: boolean;
-    connectionVerified: boolean;
-    workspaceName: string | null;
-    lastError: string | null;
-    nextAction: OnboardingNextAction;
-    docsUrl: string;
-    keySource: 'config' | 'environment' | 'persisted' | 'openclaw-config-file' | 'legacy-dev' | 'none';
-    installationId: string | null;
-    connectUrl: string | null;
-    pairingId: string | null;
-    expiresAt: string | null;
-    pollIntervalMs: number | null;
-}
 export interface OrgSnapshot {
     /** Active initiatives */
     initiatives: Initiative[];
@@ -265,7 +249,6 @@ export interface BillingUrlResult {
     url: string | null;
     checkout_url?: string | null;
 }
-export type RunPhase = 'intent' | 'execution' | 'blocked' | 'review' | 'handoff' | 'completed';
 export interface HandoffWorkspaceState {
     git?: {
         branch?: string | null;
@@ -397,7 +380,6 @@ export interface EntityListFilters {
     [key: string]: unknown;
 }
 export type ReportingSourceClient = 'openclaw' | 'codex' | 'claude-code' | 'api';
-export type RuntimeSourceClient = ReportingSourceClient | 'unknown';
 export type ReportingPhase = 'intent' | 'execution' | 'blocked' | 'review' | 'handoff' | 'completed';
 export type ReportingLevel = 'info' | 'warn' | 'error';
 export type TaskStatus = 'todo' | 'in_progress' | 'done' | 'blocked';
@@ -538,114 +520,3 @@ export interface RecordRunRetroResponse {
     event_id: string | null;
     auth_mode?: 'service' | 'api_key';
 }
-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 type RuntimeInstanceState = 'active' | 'stale' | 'stopped' | 'error';
-export interface RuntimeInstance {
-    id: string;
-    sourceClient: RuntimeSourceClient;
-    displayName: string;
-    providerLogo: 'codex' | 'openai' | 'anthropic' | 'openclaw' | 'orgx' | 'unknown';
-    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 interface LiveActivityItem {
-    id: string;
-    type: LiveActivityType;
-    title: string;
-    description: string | null;
-    agentId: string | null;
-    agentName: 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?: RuntimeInstance['providerLogo'] | null;
-    instanceId?: string | null;
-    lastHeartbeatAt?: string | null;
-    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?: RuntimeInstance['providerLogo'] | 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/types.js

@@ -5,3 +5,8 @@
  * Mirrors the server-side types in orgx/lib/client-integration/types.ts
  */
 export {};
+// =============================================================================
+// LIVE SESSION GRAPH + HANDOFFS
+// =============================================================================
+// Live/session/handoff activity shapes are imported and re-exported from
+// ./shared-types.ts to keep dashboard and plugin contracts in lockstep.

package/dist/entities/auto-assignment.d.ts

@@ -0,0 +1,36 @@
+export type AutoAssignedAgent = {
+    id: string;
+    name: string;
+    domain: string | null;
+};
+export declare function autoAssignEntityForCreate(input: {
+    client: {
+        getLiveAgents: (payload: {
+            initiative: string | null;
+            includeIdle: boolean;
+        }) => Promise<{
+            agents?: unknown[];
+        }>;
+        delegationPreflight: (payload: {
+            intent: string;
+        }) => Promise<{
+            data?: {
+                recommended_split?: Array<{
+                    owner_domain?: string | null;
+                }>;
+            };
+        }>;
+        updateEntity: (entityType: string, entityId: string, payload: Record<string, unknown>) => Promise<unknown>;
+    };
+    toErrorMessage: (err: unknown) => string;
+    entityType: string;
+    entityId: string;
+    initiativeId: string | null;
+    title: string;
+    summary: string | null;
+}): Promise<{
+    assignmentSource: "orchestrator" | "fallback" | "manual";
+    assignedAgents: AutoAssignedAgent[];
+    warnings: string[];
+    updatedEntity: Record<string, unknown> | null;
+}>;