@useorgx/openclaw-plugin 0.4.8 → 0.7.0

package/dist/contracts/client.js

@@ -12,6 +12,12 @@ const DEFAULT_SYNC_TIMEOUT_MS = 45_000;
 const USER_AGENT = "OrgX-Clawdbot-Plugin/1.0";
 const DECISION_MUTATION_CONCURRENCY = 6;
 const DEFAULT_CLIENT_BASE_URL = "https://www.useorgx.com";
+function normalizeAgentStatus(value) {
+    if (value === "active" || value === "idle" || value === "throttled") {
+        return value;
+    }
+    return "idle";
+}
 function isUserScopedApiKey(apiKey) {
     return apiKey.trim().toLowerCase().startsWith("oxk_");
 }
@@ -184,21 +190,42 @@ export class OrgXClient {
         }
         return `?${search.toString()}`;
     }
+    unwrapSyncResponse(response) {
+        if (response &&
+            typeof response === "object" &&
+            "data" in response &&
+            response.data) {
+            return response.data;
+        }
+        return response;
+    }
     // ===========================================================================
     // Org Snapshot
     // ===========================================================================
     async getOrgSnapshot() {
         // Use the sync endpoint with POST (empty body = pull only)
         const resp = await this.post("/api/client/sync", {});
-        const data = resp.data;
+        const data = this.unwrapSyncResponse(resp);
         // Transform SyncResponse to OrgSnapshot format
+        const syncAgents = Array.isArray(data.agents) ? data.agents : [];
         return {
             initiatives: data.initiatives.map(i => ({
                 id: i.id,
                 title: i.title,
                 status: i.status,
             })),
-            agents: [], // Not returned by sync endpoint
+            agents: syncAgents.map((agent) => ({
+                id: String(agent.id ?? ""),
+                name: String(agent.name ?? ""),
+                domain: String(agent.domain ?? ""),
+                status: normalizeAgentStatus(agent.status),
+                currentTask: typeof agent.currentTask === "string" && agent.currentTask.trim().length > 0
+                    ? agent.currentTask
+                    : undefined,
+                lastActive: typeof agent.lastActive === "string" && agent.lastActive.trim().length > 0
+                    ? agent.lastActive
+                    : undefined,
+            })),
             activeTasks: data.activeTasks.map(t => ({
                 id: t.id,
                 title: t.title,
@@ -219,13 +246,7 @@ export class OrgXClient {
     // ===========================================================================
     async syncMemory(payload) {
         const response = await this.post("/api/client/sync", payload);
-        if (response &&
-            typeof response === "object" &&
-            "data" in response &&
-            response.data) {
-            return response.data;
-        }
-        return response;
+        return this.unwrapSyncResponse(response);
     }
     // ===========================================================================
     // Kickoff Context
@@ -293,6 +314,20 @@ export class OrgXClient {
             clearTimeout(timeout);
         }
     }
+    // ===========================================================================
+    // Client Agent Runtime Settings
+    // ===========================================================================
+    async getClientAgentRuntimeSettings(input) {
+        const workspaceScope = input?.workspaceId ?? input?.projectId ?? null;
+        const query = this.buildQuery({
+            workspace_id: workspaceScope,
+            command_center_id: workspaceScope,
+        });
+        return this.get(`/api/client/agents/runtime-settings${query}`);
+    }
+    async updateClientAgentRuntimeSettings(payload) {
+        return this.patch("/api/client/agents/runtime-settings", payload);
+    }
     async delegationPreflight(payload) {
         return this.post("/api/client/delegation/preflight", payload);
     }
@@ -351,12 +386,34 @@ export class OrgXClient {
      * PATCH /api/entities { type, id, ...updates }
      */
     async updateEntity(type, id, updates) {
+        const result = await this.updateEntityDetailed(type, id, updates);
+        return result.entity;
+    }
+    /**
+     * Update an OrgX entity and preserve reassignment metadata when present.
+     * PATCH /api/entities { type, id, ...updates }
+     */
+    async updateEntityDetailed(type, id, updates) {
         const resp = await this.patch("/api/entities", {
             type,
             id,
             ...updates,
         });
-        return resp.data ?? resp;
+        if (resp && typeof resp === "object") {
+            const envelope = resp;
+            const entity = envelope.entity ?? envelope.data ?? resp;
+            return {
+                entity,
+                reassignment: envelope.reassignment && typeof envelope.reassignment === "object"
+                    ? envelope.reassignment
+                    : null,
+                initiative_reassignment: envelope.initiative_reassignment &&
+                    typeof envelope.initiative_reassignment === "object"
+                    ? envelope.initiative_reassignment
+                    : null,
+            };
+        }
+        return { entity: resp };
     }
     /**
      * List OrgX entities.
@@ -366,10 +423,49 @@ export class OrgXClient {
         const params = new URLSearchParams({ type });
         if (filters?.status)
             params.set("status", filters.status);
+        if (typeof filters?.offset === "number" && Number.isFinite(filters.offset)) {
+            params.set("offset", String(Math.max(0, Math.floor(filters.offset))));
+        }
+        if (filters?.search)
+            params.set("search", String(filters.search));
+        if (filters?.id)
+            params.set("id", String(filters.id));
+        if (filters?.ids) {
+            const values = Array.isArray(filters.ids)
+                ? filters.ids
+                : String(filters.ids)
+                    .split(",")
+                    .map((value) => value.trim())
+                    .filter((value) => value.length > 0);
+            if (values.length > 0) {
+                params.set("ids", values.join(","));
+            }
+        }
         if (filters?.limit)
             params.set("limit", String(filters.limit));
         if (filters?.initiative_id)
             params.set("initiative_id", String(filters.initiative_id));
+        const legacyProjectIdRaw = filters?.project_id != null ? String(filters.project_id) : null;
+        const workspaceIdRaw = filters?.workspace_id != null ? String(filters.workspace_id) : null;
+        const commandCenterIdRaw = filters?.command_center_id != null
+            ? String(filters.command_center_id)
+            : null;
+        if (workspaceIdRaw &&
+            commandCenterIdRaw &&
+            workspaceIdRaw.trim() !== commandCenterIdRaw.trim()) {
+            throw new Error("workspace_id and command_center_id must match when both are provided");
+        }
+        if (legacyProjectIdRaw &&
+            workspaceIdRaw &&
+            legacyProjectIdRaw.trim() !== workspaceIdRaw.trim()) {
+            throw new Error("project_id cannot differ from workspace_id; use workspace_id as canonical scope");
+        }
+        const workspaceId = workspaceIdRaw ?? commandCenterIdRaw ?? legacyProjectIdRaw;
+        if (workspaceId) {
+            // Canonical scope param. Keep legacy alias for backward compatibility.
+            params.set("workspace_id", workspaceId);
+            params.set("command_center_id", workspaceId);
+        }
         return this.get(`/api/entities?${params.toString()}`);
     }
     // ===========================================================================
@@ -397,6 +493,18 @@ export class OrgXClient {
         return response;
     }
     // ===========================================================================
+    // Usage (Control Plane + Forecast)
+    // ===========================================================================
+    async getUsageControlPlaneSummary() {
+        return this.get("/api/usage/control-plane/summary");
+    }
+    async getUsageUnified() {
+        return this.get("/api/usage/unified");
+    }
+    async getUsageForecast() {
+        return this.get("/api/usage/forecast");
+    }
+    // ===========================================================================
     // Reporting Control Plane
     // ===========================================================================
     async emitActivity(payload) {
@@ -443,31 +551,44 @@ export class OrgXClient {
     // Live Sessions + Activity + Handoffs
     // ===========================================================================
     async getLiveSessions(params) {
+        const workspaceScope = params?.workspaceId ?? params?.projectId ?? null;
         const query = this.buildQuery({
             limit: params?.limit,
             initiative: params?.initiative ?? null,
+            workspace_id: workspaceScope,
+            command_center_id: workspaceScope,
         });
         return this.get(`/api/client/live/sessions${query}`);
     }
     async getLiveActivity(params) {
+        const workspaceScope = params?.workspaceId ?? params?.projectId ?? null;
         const query = this.buildQuery({
             limit: params?.limit,
             run: params?.run ?? null,
             since: params?.since ?? null,
+            workspace_id: workspaceScope,
+            command_center_id: workspaceScope,
         });
         return this.get(`/api/client/live/activity${query}`);
     }
     async getLiveAgents(params) {
+        const workspaceScope = params?.workspaceId ?? params?.projectId ?? null;
         const query = this.buildQuery({
             initiative: params?.initiative ?? null,
             include_idle: params?.includeIdle ?? undefined,
+            workspace_id: workspaceScope,
+            command_center_id: workspaceScope,
         });
         return this.get(`/api/client/live/agents${query}`);
     }
     async getLiveInitiatives(params) {
+        const workspaceScope = params?.workspaceId ?? params?.projectId ?? null;
         const query = this.buildQuery({
             id: params?.id ?? null,
             limit: params?.limit ?? null,
+            offset: params?.offset ?? null,
+            workspace_id: workspaceScope,
+            command_center_id: workspaceScope,
         });
         return this.get(`/api/client/live/initiatives${query}`);
     }
@@ -493,9 +614,12 @@ export class OrgXClient {
         return this.post(`/api/client/runs/${encodedRunId}/checkpoints/${encodedCheckpointId}/restore`, { reason: request.reason });
     }
     async getLiveDecisions(params) {
+        const workspaceScope = params?.workspaceId ?? params?.projectId ?? undefined;
         const response = await this.listEntities("decision", {
             status: params?.status,
             limit: params?.limit,
+            workspace_id: workspaceScope,
+            command_center_id: workspaceScope,
         });
         const decisions = Array.isArray(response.data) ? response.data : [];
         return {
@@ -503,32 +627,37 @@ export class OrgXClient {
             total: response.pagination?.total ?? decisions.length,
         };
     }
-    async decideDecision(id, action, note) {
-        const resolvedStatus = action === "approve" ? "approved" : "rejected";
-        const resolvedAt = new Date().toISOString();
+    async decideDecision(id, action, input) {
+        const note = input?.note?.trim() || null;
+        const optionId = input?.optionId?.trim() || null;
+        const resolvedStatus = action === "approve" ? "approved" : "declined";
+        const primaryPatch = {
+            status: resolvedStatus,
+            ...(note ? { resolution_summary: note } : {}),
+            ...(optionId ? { option_id: optionId } : {}),
+        };
         try {
-            return await this.updateEntity("decision", id, {
-                status: resolvedStatus,
-                resolution: resolvedStatus,
-                resolved_at: resolvedAt,
-                decided_at: resolvedAt,
-                decided_by: this.userId || undefined,
-                note: note ?? undefined,
-            });
+            return await this.updateEntity("decision", id, primaryPatch);
         }
         catch {
-            // Fallback for backends that only support generic "resolved" status.
+            // Keep fallback payload schema-safe for strict entity routes.
             return this.updateEntity("decision", id, {
-                status: "resolved",
-                decision_status: resolvedStatus,
-                resolution: resolvedStatus,
-                resolved_at: resolvedAt,
-                decided_at: resolvedAt,
-                note: note ?? undefined,
+                status: resolvedStatus,
+                ...(note
+                    ? {
+                        metadata: {
+                            resolution: {
+                                summary: note,
+                                note,
+                            },
+                        },
+                    }
+                    : {}),
+                ...(optionId ? { option_id: optionId } : {}),
             });
         }
     }
-    async bulkDecideDecisions(ids, action, note) {
+    async bulkDecideDecisions(ids, action, input) {
         const uniqueIds = Array.from(new Set(ids.filter(Boolean)));
         const results = new Array(uniqueIds.length);
         let cursor = 0;
@@ -541,7 +670,7 @@ export class OrgXClient {
                 }
                 const id = uniqueIds[index];
                 try {
-                    const entity = await this.decideDecision(id, action, note);
+                    const entity = await this.decideDecision(id, action, input);
                     results[index] = { id, ok: true, entity };
                 }
                 catch (err) {

package/dist/contracts/retro-schema.d.ts

@@ -0,0 +1,81 @@
+export declare const RETRO_ARTIFACT_SCHEMA_VERSION: "retro.v1";
+export type RetroArtifactSchemaVersion = typeof RETRO_ARTIFACT_SCHEMA_VERSION;
+export declare const RETRO_ARTIFACT_JSON_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://schemas.useorgx.com/retro-artifact/v1.json";
+    readonly title: "OrgX Run Retro Artifact v1";
+    readonly description: "Structured post-run retrospective artifact emitted by OpenClaw/OrgX execution paths.";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schema_version", "summary"];
+    readonly properties: {
+        readonly schema_version: {
+            readonly type: "string";
+            readonly const: "retro.v1";
+            readonly description: "Version marker for safe schema evolution.";
+        };
+        readonly summary: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 4000;
+            readonly description: "Required high-level run retrospective summary.";
+        };
+        readonly what_went_well: {
+            readonly type: "array";
+            readonly maxItems: 25;
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 1000;
+            };
+        };
+        readonly what_went_wrong: {
+            readonly type: "array";
+            readonly maxItems: 25;
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 1000;
+            };
+        };
+        readonly decisions: {
+            readonly type: "array";
+            readonly maxItems: 25;
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 1000;
+            };
+        };
+        readonly follow_ups: {
+            readonly type: "array";
+            readonly maxItems: 25;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["title"];
+                readonly properties: {
+                    readonly title: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 500;
+                    };
+                    readonly priority: {
+                        readonly type: "string";
+                        readonly enum: readonly ["p0", "p1", "p2"];
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 2000;
+                    };
+                };
+            };
+        };
+        readonly signals: {
+            readonly type: "object";
+            readonly additionalProperties: true;
+            readonly description: "Telemetry-style structured metadata for analytics and drill-down.";
+        };
+    };
+};

package/dist/contracts/retro-schema.js

@@ -0,0 +1,80 @@
+export const RETRO_ARTIFACT_SCHEMA_VERSION = 'retro.v1';
+export const RETRO_ARTIFACT_JSON_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://schemas.useorgx.com/retro-artifact/v1.json',
+    title: 'OrgX Run Retro Artifact v1',
+    description: 'Structured post-run retrospective artifact emitted by OpenClaw/OrgX execution paths.',
+    type: 'object',
+    additionalProperties: false,
+    required: ['schema_version', 'summary'],
+    properties: {
+        schema_version: {
+            type: 'string',
+            const: RETRO_ARTIFACT_SCHEMA_VERSION,
+            description: 'Version marker for safe schema evolution.',
+        },
+        summary: {
+            type: 'string',
+            minLength: 1,
+            maxLength: 4000,
+            description: 'Required high-level run retrospective summary.',
+        },
+        what_went_well: {
+            type: 'array',
+            maxItems: 25,
+            items: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 1000,
+            },
+        },
+        what_went_wrong: {
+            type: 'array',
+            maxItems: 25,
+            items: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 1000,
+            },
+        },
+        decisions: {
+            type: 'array',
+            maxItems: 25,
+            items: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 1000,
+            },
+        },
+        follow_ups: {
+            type: 'array',
+            maxItems: 25,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['title'],
+                properties: {
+                    title: {
+                        type: 'string',
+                        minLength: 1,
+                        maxLength: 500,
+                    },
+                    priority: {
+                        type: 'string',
+                        enum: ['p0', 'p1', 'p2'],
+                    },
+                    reason: {
+                        type: 'string',
+                        minLength: 1,
+                        maxLength: 2000,
+                    },
+                },
+            },
+        },
+        signals: {
+            type: 'object',
+            additionalProperties: true,
+            description: 'Telemetry-style structured metadata for analytics and drill-down.',
+        },
+    },
+};