@useorgx/openclaw-plugin 0.4.5 → 0.4.8

package/dist/artifacts/register-artifact.js

@@ -0,0 +1,271 @@
+import { randomUUID } from "node:crypto";
+const MAX_PREVIEW_MARKDOWN = 25_000;
+function normalizeText(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function isUuid(value) {
+    return /^[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(value);
+}
+function resolveCreatedById(client, input) {
+    const explicit = normalizeText(input.created_by_id);
+    if (explicit && isUuid(explicit))
+        return explicit;
+    const fromClient = typeof client?.getUserId === "function"
+        ? normalizeText(client.getUserId())
+        : "";
+    if (fromClient && isUuid(fromClient))
+        return fromClient;
+    const fromEnv = normalizeText(process.env.ORGX_CREATED_BY_ID);
+    if (fromEnv && isUuid(fromEnv))
+        return fromEnv;
+    return null;
+}
+export function validateRegisterArtifactInput(input) {
+    const errors = [];
+    if (!input || typeof input !== "object") {
+        return ["input must be an object"];
+    }
+    const entityType = normalizeText(input.entity_type);
+    if (!entityType)
+        errors.push("entity_type is required");
+    const entityId = normalizeText(input.entity_id);
+    if (!entityId)
+        errors.push("entity_id is required");
+    // In production OrgX uses UUIDs, but tests/mocks sometimes use short ids like "init-1".
+    // Keep this as a soft constraint (persistence validation will catch mismatches upstream).
+    const name = normalizeText(input.name);
+    if (!name)
+        errors.push("name is required");
+    const artifactType = normalizeText(input.artifact_type);
+    if (!artifactType)
+        errors.push("artifact_type is required");
+    const createdByType = normalizeText(input.created_by_type);
+    if (createdByType && createdByType !== "human" && createdByType !== "agent") {
+        errors.push("created_by_type must be 'human' or 'agent' when provided");
+    }
+    const externalUrl = normalizeText(input.external_url);
+    const preview = normalizeText(input.preview_markdown);
+    if (!externalUrl && !preview) {
+        errors.push("at least one of external_url or preview_markdown is required");
+    }
+    return errors;
+}
+function safeErrorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+function isArtifactTypeConstraintError(err) {
+    const msg = safeErrorMessage(err).toLowerCase();
+    return (msg.includes("artifact_type") &&
+        (msg.includes("constraint") || msg.includes("foreign") || msg.includes("violat")));
+}
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, "");
+}
+async function sleep(ms) {
+    await new Promise((r) => setTimeout(r, ms));
+}
+async function validateArtifactPersistence(client, input) {
+    // Use API-key compatible entity CRUD endpoints for validation.
+    // The web UI endpoints (/api/artifacts/*, /api/work-artifacts/*) are session-authenticated (401 for API keys).
+    const detail = await client.rawRequest("GET", `/api/entities?type=artifact&id=${encodeURIComponent(input.artifactId)}`);
+    const rows = detail && typeof detail === "object" ? detail.data : null;
+    const artifact = Array.isArray(rows) ? rows.find((r) => r && typeof r === "object" && r.id === input.artifactId) : null;
+    const artifactOk = artifact && typeof artifact === "object" && typeof artifact.id === "string" && artifact.id === input.artifactId;
+    const linkedOk = artifactOk &&
+        typeof artifact.entity_type === "string" &&
+        typeof artifact.entity_id === "string" &&
+        artifact.entity_type === input.entity_type &&
+        artifact.entity_id === input.entity_id;
+    return { artifact_detail_ok: Boolean(artifactOk), linked_ok: Boolean(linkedOk) };
+}
+export async function registerArtifact(client, baseUrl, input) {
+    const warnings = [];
+    const errors = validateRegisterArtifactInput(input);
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            artifact_id: null,
+            artifact_url: null,
+            created: false,
+            persistence: {
+                checked: false,
+                artifact_detail_ok: false,
+                linked_ok: false,
+                attempts: 0,
+                last_error: errors.join("; "),
+            },
+            warnings: [],
+        };
+    }
+    const requestedId = normalizeText(input.artifact_id);
+    const desiredId = requestedId && isUuid(requestedId) ? requestedId : randomUUID();
+    const artifactUrl = `${normalizeBaseUrl(baseUrl)}/artifacts/${desiredId}`;
+    const status = normalizeText(input.status) || "draft";
+    const createdByType = normalizeText(input.created_by_type) || "human";
+    const createdById = resolveCreatedById(client, input);
+    const createdBy = createdById ? { created_by_type: createdByType, created_by_id: createdById } : { created_by_type: createdByType };
+    const metadata = {
+        ...(input.metadata && typeof input.metadata === "object" && !Array.isArray(input.metadata)
+            ? input.metadata
+            : {}),
+    };
+    if (input.external_url)
+        metadata.external_url = String(input.external_url);
+    if (input.preview_markdown) {
+        const preview = String(input.preview_markdown);
+        metadata.preview_markdown =
+            preview.length > MAX_PREVIEW_MARKDOWN
+                ? preview.slice(0, MAX_PREVIEW_MARKDOWN)
+                : preview;
+        if (preview.length > MAX_PREVIEW_MARKDOWN)
+            metadata.preview_truncated = true;
+    }
+    const metadataInitiativeId = typeof metadata.initiative_id === "string" && metadata.initiative_id.trim().length > 0
+        ? metadata.initiative_id.trim()
+        : null;
+    const initiativeIdHint = input.entity_type === "initiative" ? input.entity_id : metadataInitiativeId;
+    let entity = null;
+    let created = false;
+    // Attempt idempotent create using a client-provided UUID id (preferred).
+    try {
+        try {
+            entity = await client.createEntity("artifact", {
+                id: desiredId,
+                name: input.name,
+                description: input.description ?? undefined,
+                artifact_type: input.artifact_type,
+                entity_type: input.entity_type,
+                entity_id: input.entity_id,
+                ...(initiativeIdHint ? { initiative_id: initiativeIdHint } : {}),
+                artifact_url: artifactUrl,
+                status,
+                metadata,
+                ...createdBy,
+            });
+            created = true;
+        }
+        catch (err) {
+            if (!isArtifactTypeConstraintError(err)) {
+                throw err;
+            }
+            warnings.push(`artifact_type rejected; retrying with shared.project_handbook`);
+            metadata.requested_artifact_type = input.artifact_type;
+            entity = await client.createEntity("artifact", {
+                id: desiredId,
+                name: input.name,
+                description: input.description ?? undefined,
+                artifact_type: "shared.project_handbook",
+                entity_type: input.entity_type,
+                entity_id: input.entity_id,
+                ...(initiativeIdHint ? { initiative_id: initiativeIdHint } : {}),
+                artifact_url: artifactUrl,
+                status,
+                metadata,
+                ...createdBy,
+            });
+            created = true;
+        }
+    }
+    catch (err) {
+        warnings.push(`artifact create with explicit id failed: ${safeErrorMessage(err)}`);
+        // Fallback: create without id, then patch artifact_url once we know the server id.
+        try {
+            entity = await client.createEntity("artifact", {
+                name: input.name,
+                description: input.description ?? undefined,
+                artifact_type: input.artifact_type,
+                entity_type: input.entity_type,
+                entity_id: input.entity_id,
+                ...(initiativeIdHint ? { initiative_id: initiativeIdHint } : {}),
+                artifact_url: input.external_url ?? `${normalizeBaseUrl(baseUrl)}/artifacts/pending`,
+                status,
+                metadata,
+                ...createdBy,
+            });
+            created = true;
+        }
+        catch (inner) {
+            if (!isArtifactTypeConstraintError(inner)) {
+                throw inner;
+            }
+            warnings.push(`artifact_type rejected; retrying with shared.project_handbook`);
+            metadata.requested_artifact_type = input.artifact_type;
+            entity = await client.createEntity("artifact", {
+                name: input.name,
+                description: input.description ?? undefined,
+                artifact_type: "shared.project_handbook",
+                entity_type: input.entity_type,
+                entity_id: input.entity_id,
+                ...(initiativeIdHint ? { initiative_id: initiativeIdHint } : {}),
+                artifact_url: input.external_url ?? `${normalizeBaseUrl(baseUrl)}/artifacts/pending`,
+                status,
+                metadata,
+                ...createdBy,
+            });
+            created = true;
+        }
+    }
+    const artifactId = entity && typeof entity === "object" && typeof entity.id === "string"
+        ? String(entity.id)
+        : null;
+    let finalArtifactUrl = artifactId
+        ? `${normalizeBaseUrl(baseUrl)}/artifacts/${artifactId}`
+        : null;
+    if (artifactId) {
+        try {
+            await client.updateEntity("artifact", artifactId, {
+                artifact_url: finalArtifactUrl,
+            });
+        }
+        catch (err) {
+            warnings.push(`artifact_url patch failed: ${safeErrorMessage(err)}`);
+            // Keep whatever we sent originally.
+            finalArtifactUrl = typeof entity?.artifact_url === "string" ? entity.artifact_url : finalArtifactUrl;
+        }
+    }
+    const shouldValidate = input.validate_persistence === true;
+    const persistence = {
+        checked: false,
+        artifact_detail_ok: false,
+        linked_ok: false,
+        attempts: 0,
+        last_error: null,
+    };
+    if (shouldValidate && artifactId) {
+        persistence.checked = true;
+        const maxAttempts = 4;
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            persistence.attempts = attempt;
+            try {
+                const result = await validateArtifactPersistence(client, {
+                    artifactId,
+                    entity_type: input.entity_type,
+                    entity_id: input.entity_id,
+                });
+                persistence.artifact_detail_ok = result.artifact_detail_ok;
+                persistence.linked_ok = result.linked_ok;
+                if (result.artifact_detail_ok && result.linked_ok) {
+                    break;
+                }
+            }
+            catch (err) {
+                persistence.last_error = safeErrorMessage(err);
+            }
+            // quick backoff for eventual consistency
+            await sleep(250 * attempt);
+        }
+        if (!persistence.artifact_detail_ok || !persistence.linked_ok) {
+            warnings.push(`artifact persistence check failed (detail_ok=${persistence.artifact_detail_ok}, linked_ok=${persistence.linked_ok})`);
+        }
+    }
+    return {
+        ok: Boolean(artifactId),
+        artifact_id: artifactId,
+        artifact_url: finalArtifactUrl,
+        created,
+        persistence,
+        warnings,
+    };
+}

package/dist/auth-store.js

@@ -14,6 +14,9 @@ function installationFile() {
 function isUserScopedApiKey(apiKey) {
     return apiKey.trim().toLowerCase().startsWith('oxk_');
 }
+function isUuid(value) {
+    return /^[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(value);
+}
 function ensureAuthDir() {
     const dir = authDir();
     mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -49,17 +52,6 @@ export function readPersistedAuth() {
         if (!parsed || typeof parsed.apiKey !== 'string' || parsed.apiKey.trim().length === 0) {
             return null;
         }
-        if (isUserScopedApiKey(parsed.apiKey) &&
-            typeof parsed.userId === 'string' &&
-            parsed.userId.trim().length > 0) {
-            const sanitized = {
-                ...parsed,
-                userId: null,
-                updatedAt: new Date().toISOString(),
-            };
-            writeJsonFileAtomicSync(file, sanitized, 0o600);
-            return sanitized;
-        }
         return parsed;
     }
     catch {
@@ -70,9 +62,12 @@ export function writePersistedAuth(input) {
     ensureAuthDir();
     const now = new Date().toISOString();
     const existing = readPersistedAuth();
-    const normalizedUserId = isUserScopedApiKey(input.apiKey)
+    const rawUserId = typeof input.userId === 'string' ? input.userId.trim() : '';
+    const normalizedUserId = rawUserId.length === 0
         ? null
-        : input.userId ?? null;
+        : isUserScopedApiKey(input.apiKey)
+            ? (isUuid(rawUserId) ? rawUserId : null)
+            : rawUserId;
     const next = {
         apiKey: input.apiKey,
         source: input.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, LiveActivityItem, SessionTreeResponse, HandoffSummary, CheckpointSummary, RestoreRequest, DelegationPreflightResult, BillingStatus, BillingCheckoutRequest, BillingUrlResult } from "./types.js";
+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";
 export type DecisionAction = "approve" | "reject";
 export type RunAction = "pause" | "resume" | "cancel" | "rollback";
 export interface DecisionActionResult {
@@ -26,6 +26,7 @@ export declare class OrgXClient {
         baseUrl?: string;
     }): void;
     getBaseUrl(): string;
+    getUserId(): string;
     /**
      * Low-level authenticated request helper.
      *
@@ -41,6 +42,25 @@ export declare class OrgXClient {
     private buildQuery;
     getOrgSnapshot(): Promise<OrgSnapshot>;
     syncMemory(payload: SyncPayload): Promise<SyncResponse>;
+    getKickoffContext(payload: KickoffContextRequest): Promise<KickoffContextResponse>;
+    getSkillPack(input?: {
+        name?: string;
+        ifNoneMatch?: string | null;
+    }): Promise<{
+        ok: true;
+        notModified: true;
+        etag: string | null;
+        pack: null;
+    } | {
+        ok: true;
+        notModified: false;
+        etag: string | null;
+        pack: SkillPack;
+    } | {
+        ok: false;
+        status: number;
+        error: string;
+    }>;
     delegationPreflight(payload: {
         intent: string;
         acceptanceCriteria?: string[];
@@ -80,6 +100,8 @@ export declare class OrgXClient {
     createBillingPortal(): Promise<BillingUrlResult>;
     emitActivity(payload: EmitActivityRequest): Promise<EmitActivityResponse>;
     applyChangeset(payload: ApplyChangesetRequest): Promise<ApplyChangesetResponse>;
+    recordRunOutcome(payload: RecordRunOutcomeRequest): Promise<RecordRunOutcomeResponse>;
+    recordRunRetro(payload: RecordRunRetroRequest): Promise<RecordRunRetroResponse>;
     getLiveSessions(params?: {
         limit?: number;
         initiative?: string | null;

package/dist/contracts/client.js

@@ -6,13 +6,43 @@
  *
  * Uses native fetch — no external dependencies.
  */
-const REQUEST_TIMEOUT_MS = 10_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 25_000;
+const DEFAULT_LIVE_TIMEOUT_MS = 30_000;
+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 isUserScopedApiKey(apiKey) {
     return apiKey.trim().toLowerCase().startsWith("oxk_");
 }
+function parseTimeoutMsEnv(name) {
+    const raw = process.env[name];
+    if (!raw)
+        return null;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return null;
+    // Keep it sane: timeouts below 1s tend to create pathological "offline" loops.
+    return Math.max(1_000, Math.floor(parsed));
+}
+function resolveRequestTimeoutMs(path) {
+    const configured = parseTimeoutMsEnv("ORGX_HTTP_TIMEOUT_MS") ??
+        parseTimeoutMsEnv("ORGX_API_TIMEOUT_MS");
+    const base = configured ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    // Live endpoints frequently return larger payloads (sessions, activity, agents).
+    if (path.startsWith("/api/client/live/")) {
+        return Math.max(base, DEFAULT_LIVE_TIMEOUT_MS);
+    }
+    // Sync can include a full org snapshot and may take longer than typical CRUD.
+    if (path === "/api/client/sync") {
+        return Math.max(base, DEFAULT_SYNC_TIMEOUT_MS);
+    }
+    // Handoffs can require server-side aggregation.
+    if (path === "/api/client/handoffs") {
+        return Math.max(base, DEFAULT_LIVE_TIMEOUT_MS);
+    }
+    return base;
+}
 function normalizeHost(value) {
     return value.trim().toLowerCase().replace(/^\[|\]$/g, "");
 }
@@ -50,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);
@@ -69,6 +98,9 @@ export class OrgXClient {
     getBaseUrl() {
         return this.baseUrl;
     }
+    getUserId() {
+        return this.userId;
+    }
     // ===========================================================================
     // HTTP helpers
     // ===========================================================================
@@ -85,7 +117,8 @@ export class OrgXClient {
     async request(method, path, body) {
         const url = `${this.baseUrl}${path}`;
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        const timeoutMs = resolveRequestTimeoutMs(path);
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
         try {
             const headers = {
                 "Content-Type": "application/json",
@@ -124,7 +157,7 @@ export class OrgXClient {
         }
         catch (err) {
             if (err instanceof DOMException && err.name === "AbortError") {
-                throw new Error(`OrgX API ${method} ${path} timed out after ${REQUEST_TIMEOUT_MS}ms`);
+                throw new Error(`OrgX API ${method} ${path} timed out after ${timeoutMs}ms`);
             }
             throw err;
         }
@@ -194,6 +227,72 @@ export class OrgXClient {
         }
         return response;
     }
+    // ===========================================================================
+    // Kickoff Context
+    // ===========================================================================
+    async getKickoffContext(payload) {
+        return await this.post("/api/client/kickoff-context", payload ?? {});
+    }
+    // ===========================================================================
+    // Skill Packs (ETag-aware)
+    // ===========================================================================
+    async getSkillPack(input) {
+        const name = (input?.name ?? "").trim() || "orgx-agent-suite";
+        const url = `${this.baseUrl}/api/client/skill-pack?name=${encodeURIComponent(name)}`;
+        const controller = new AbortController();
+        const timeoutMs = resolveRequestTimeoutMs("/api/client/skill-pack");
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const headers = {
+                "Content-Type": "application/json",
+                "User-Agent": USER_AGENT,
+                Authorization: `Bearer ${this.apiKey}`,
+            };
+            if (this.userId && !isUserScopedApiKey(this.apiKey)) {
+                headers["X-Orgx-User-Id"] = this.userId;
+            }
+            const ifNoneMatch = (input?.ifNoneMatch ?? "").trim();
+            if (ifNoneMatch) {
+                headers["If-None-Match"] = ifNoneMatch;
+            }
+            const response = await fetch(url, {
+                method: "GET",
+                headers,
+                signal: controller.signal,
+            });
+            const etag = response.headers.get("etag");
+            if (response.status === 304) {
+                return { ok: true, notModified: true, etag, pack: null };
+            }
+            const contentType = response.headers.get("content-type") ?? "";
+            const payload = contentType.includes("application/json")
+                ? (await response.json().catch(() => null))
+                : null;
+            if (!response.ok) {
+                const detail = payload && typeof payload === "object" && "error" in payload && typeof payload.error === "string"
+                    ? payload.error
+                    : `${response.status} ${response.statusText}`;
+                return { ok: false, status: response.status, error: detail };
+            }
+            if (payload && typeof payload === "object" && payload.ok === true && payload.data) {
+                return { ok: true, notModified: false, etag, pack: payload.data };
+            }
+            return { ok: false, status: 502, error: "SkillPack response was invalid" };
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === "AbortError") {
+                return {
+                    ok: false,
+                    status: 504,
+                    error: `OrgX API GET /api/client/skill-pack timed out after ${timeoutMs}ms`,
+                };
+            }
+            return { ok: false, status: 502, error: err instanceof Error ? err.message : "SkillPack request failed" };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
     async delegationPreflight(payload) {
         return this.post("/api/client/delegation/preflight", payload);
     }
@@ -320,6 +419,26 @@ export class OrgXClient {
         }
         return response;
     }
+    async recordRunOutcome(payload) {
+        const response = await this.post("/api/client/live/runs/outcomes/record", payload);
+        if (response &&
+            typeof response === "object" &&
+            "data" in response &&
+            response.data) {
+            return response.data;
+        }
+        return response;
+    }
+    async recordRunRetro(payload) {
+        const response = await this.post("/api/client/live/runs/retro", payload);
+        if (response &&
+            typeof response === "object" &&
+            "data" in response &&
+            response.data) {
+            return response.data;
+        }
+        return response;
+    }
     // ===========================================================================
     // Live Sessions + Activity + Handoffs
     // ===========================================================================