@useorgx/openclaw-plugin 0.4.9 → 0.7.2

package/dist/artifacts/register-artifact.js

@@ -1,8 +1,25 @@
 import { randomUUID } from "node:crypto";
+import { stableHash } from "../hash-utils.js";
+import { validateArtifactMetadata, normalizeArtifactType, } from "./artifact-domain-schemas.js";
+const ALLOWED_ENTITY_TYPES = new Set([
+    "initiative",
+    "workstream",
+    "milestone",
+    "task",
+    "decision",
+    "project",
+]);
 const MAX_PREVIEW_MARKDOWN = 25_000;
 function normalizeText(value) {
     return typeof value === "string" ? value.trim() : "";
 }
+function normalizeConfidenceScore(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    if (value < 0 || value > 1)
+        return null;
+    return value;
+}
 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);
 }
@@ -28,6 +45,9 @@ export function validateRegisterArtifactInput(input) {
     const entityType = normalizeText(input.entity_type);
     if (!entityType)
         errors.push("entity_type is required");
+    else if (!ALLOWED_ENTITY_TYPES.has(entityType)) {
+        errors.push("entity_type must be one of: initiative, workstream, milestone, task, decision, project");
+    }
     const entityId = normalizeText(input.entity_id);
     if (!entityId)
         errors.push("entity_id is required");
@@ -39,6 +59,10 @@ export function validateRegisterArtifactInput(input) {
     const artifactType = normalizeText(input.artifact_type);
     if (!artifactType)
         errors.push("artifact_type is required");
+    if (typeof input.confidence_score !== "undefined" &&
+        normalizeConfidenceScore(input.confidence_score) == null) {
+        errors.push("confidence_score must be a number between 0 and 1 when provided");
+    }
     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");
@@ -60,6 +84,44 @@ function isArtifactTypeConstraintError(err) {
     return (msg.includes("artifact_type") &&
         (msg.includes("constraint") || msg.includes("foreign") || msg.includes("violat")));
 }
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function extractArtifactFromCreateResponse(payload) {
+    if (!isRecord(payload))
+        return null;
+    if (isRecord(payload.artifact))
+        return payload.artifact;
+    if (isRecord(payload.data) && isRecord(payload.data.artifact)) {
+        return payload.data.artifact;
+    }
+    if (isRecord(payload.data))
+        return payload.data;
+    return null;
+}
+function extractArtifactFromDetailResponse(payload) {
+    if (!isRecord(payload))
+        return null;
+    if (isRecord(payload.artifact))
+        return payload.artifact;
+    if (isRecord(payload.data) && isRecord(payload.data.artifact)) {
+        return payload.data.artifact;
+    }
+    if (isRecord(payload.data))
+        return payload.data;
+    return null;
+}
+function extractArtifactsFromListResponse(payload) {
+    if (!isRecord(payload))
+        return [];
+    const direct = payload.artifacts;
+    if (Array.isArray(direct))
+        return direct.filter(isRecord);
+    if (isRecord(payload.data) && Array.isArray(payload.data.artifacts)) {
+        return payload.data.artifacts.filter(isRecord);
+    }
+    return [];
+}
 function normalizeBaseUrl(baseUrl) {
     return baseUrl.replace(/\/+$/, "");
 }
@@ -67,18 +129,20 @@ 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) };
+    const detail = await client.rawRequest("GET", `/api/client/artifacts/${encodeURIComponent(input.artifactId)}`);
+    const detailArtifact = extractArtifactFromDetailResponse(detail);
+    const detailOk = Boolean(detailArtifact && typeof detailArtifact.id === "string" && detailArtifact.id === input.artifactId);
+    const list = await client.rawRequest("GET", `/api/client/artifacts/by-entity?entity_type=${encodeURIComponent(input.entity_type)}&entity_id=${encodeURIComponent(input.entity_id)}&limit=25`);
+    const artifacts = extractArtifactsFromListResponse(list);
+    const linkedArtifact = artifacts.find((artifact) => {
+        return (typeof artifact.id === "string" &&
+            artifact.id === input.artifactId &&
+            typeof artifact.entity_type === "string" &&
+            artifact.entity_type === input.entity_type &&
+            typeof artifact.entity_id === "string" &&
+            artifact.entity_id === input.entity_id);
+    });
+    return { artifact_detail_ok: detailOk, linked_ok: Boolean(linkedArtifact) };
 }
 export async function registerArtifact(client, baseUrl, input) {
     const warnings = [];
@@ -111,6 +175,9 @@ export async function registerArtifact(client, baseUrl, input) {
             ? input.metadata
             : {}),
     };
+    const confidenceScore = normalizeConfidenceScore(input.confidence_score);
+    if (confidenceScore != null)
+        metadata.confidence_score = confidenceScore;
     if (input.external_url)
         metadata.external_url = String(input.external_url);
     if (input.preview_markdown) {
@@ -122,20 +189,102 @@ export async function registerArtifact(client, baseUrl, input) {
         if (preview.length > MAX_PREVIEW_MARKDOWN)
             metadata.preview_truncated = true;
     }
+    // --- Proof Ladder: atomic unit normalization + schema validation ---
+    const explicitAtomicType = typeof metadata.atomic_unit_type === "string"
+        ? metadata.atomic_unit_type.trim()
+        : null;
+    const inferredAtomicType = normalizeArtifactType(input.artifact_type);
+    const atomicUnitType = explicitAtomicType || inferredAtomicType;
+    if (atomicUnitType) {
+        metadata.atomic_unit_type = atomicUnitType;
+        const validation = validateArtifactMetadata(atomicUnitType, metadata);
+        metadata.schema_validated = validation.valid;
+        if (!validation.valid) {
+            warnings.push(...validation.warnings);
+        }
+    }
+    // --- Proof Ladder: artifact content hash ---
+    const hashSource = input.preview_markdown || input.external_url || input.name;
+    if (hashSource && !metadata.artifact_hash) {
+        metadata.artifact_hash = stableHash(String(hashSource));
+    }
+    // --- Proof Ladder: queue_ref from environment / caller ---
+    if (!metadata.queue_ref) {
+        const queueRef = {};
+        const envInitId = normalizeText(process.env.ORGX_INITIATIVE_ID);
+        const envWsId = normalizeText(process.env.ORGX_WORKSTREAM_ID);
+        const envTaskId = normalizeText(process.env.ORGX_TASK_ID);
+        if (envInitId)
+            queueRef.initiative_id = envInitId;
+        if (envWsId)
+            queueRef.workstream_id = envWsId;
+        if (envTaskId)
+            queueRef.task_id = envTaskId;
+        if (Object.keys(queueRef).length > 0) {
+            metadata.queue_ref = queueRef;
+        }
+    }
+    // --- Proof Ladder: run_ref from environment / caller ---
+    if (!metadata.run_ref) {
+        const runRef = {};
+        const envRunId = normalizeText(process.env.ORGX_RUN_ID);
+        const envCorrId = normalizeText(process.env.ORGX_CORRELATION_ID);
+        const envSessionId = normalizeText(process.env.ORGX_SESSION_ID);
+        if (envRunId)
+            runRef.run_id = envRunId;
+        if (envCorrId)
+            runRef.correlation_id = envCorrId;
+        if (envSessionId)
+            runRef.session_id = envSessionId;
+        if (Object.keys(runRef).length > 0) {
+            metadata.run_ref = runRef;
+        }
+    }
     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).
+    let usedLegacyCreate = false;
+    // Primary path: canonical client artifact contract.
     try {
+        const response = await client.rawRequest("POST", "/api/client/artifacts", {
+            artifact_id: desiredId,
+            entity_type: input.entity_type,
+            entity_id: input.entity_id,
+            name: input.name,
+            artifact_type: input.artifact_type,
+            description: input.description ?? undefined,
+            artifact_url: artifactUrl,
+            external_url: input.external_url ?? undefined,
+            preview_markdown: input.preview_markdown ?? undefined,
+            status,
+            metadata,
+            ...(initiativeIdHint ? { initiative_id: initiativeIdHint } : {}),
+            ...createdBy,
+        });
+        entity = extractArtifactFromCreateResponse(response);
+        if (!entity) {
+            warnings.push("client artifact create returned an unexpected payload shape");
+        }
+        else {
+            created = true;
+        }
+    }
+    catch (err) {
+        warnings.push(`client artifact create failed; falling back to legacy entities route: ${safeErrorMessage(err)}`);
+    }
+    // Compatibility path for older OrgX servers.
+    if (!entity) {
+        usedLegacyCreate = true;
         try {
             entity = await client.createEntity("artifact", {
                 id: desiredId,
                 name: input.name,
                 description: input.description ?? undefined,
                 artifact_type: input.artifact_type,
+                confidence_score: confidenceScore ?? undefined,
                 entity_type: input.entity_type,
                 entity_id: input.entity_id,
                 ...(initiativeIdHint ? { initiative_id: initiativeIdHint } : {}),
@@ -150,13 +299,14 @@ export async function registerArtifact(client, baseUrl, input) {
             if (!isArtifactTypeConstraintError(err)) {
                 throw err;
             }
-            warnings.push(`artifact_type rejected; retrying with shared.project_handbook`);
+            warnings.push(`artifact_type rejected on legacy route; 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",
+                confidence_score: confidenceScore ?? undefined,
                 entity_type: input.entity_type,
                 entity_id: input.entity_id,
                 ...(initiativeIdHint ? { initiative_id: initiativeIdHint } : {}),
@@ -168,52 +318,15 @@ export async function registerArtifact(client, baseUrl, input) {
             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) {
+    let finalArtifactUrl = entity && typeof entity === "object" && typeof entity.artifact_url === "string"
+        ? String(entity.artifact_url)
+        : artifactId
+            ? `${normalizeBaseUrl(baseUrl)}/artifacts/${artifactId}`
+            : null;
+    if (artifactId && usedLegacyCreate) {
         try {
             await client.updateEntity("artifact", artifactId, {
                 artifact_url: finalArtifactUrl,

package/dist/chat-store.d.ts

@@ -0,0 +1,157 @@
+export type ChatAttachmentState = "preparing" | "indexing" | "ready" | "failed";
+export type ChatMessageRole = "user" | "agent" | "system";
+export type ChatLaunchStatus = "requested" | "queued" | "running" | "blocked" | "completed" | "failed";
+export type ChatThreadStatus = "message_only" | "queued" | "running" | "blocked" | "completed" | "failed";
+export type ChatAttachmentRecord = {
+    id: string;
+    name: string;
+    mimeType: string | null;
+    sizeBytes: number | null;
+    status: ChatAttachmentState;
+    error: string | null;
+    masked: boolean;
+    createdAt: string;
+    updatedAt: string;
+};
+export type ChatMessageRecord = {
+    id: string;
+    threadId: string;
+    role: ChatMessageRole;
+    body: string;
+    senderId: string | null;
+    senderName: string | null;
+    createdAt: string;
+    updatedAt: string;
+    attachments: ChatAttachmentRecord[];
+    metadata: Record<string, unknown>;
+};
+export type ChatLaunchAttemptRecord = {
+    id: string;
+    threadId: string;
+    messageId: string;
+    assigneeId: string | null;
+    assigneeName: string | null;
+    watcherIds: string[];
+    watcherNames: string[];
+    executionMode: "local_queue" | "cloud" | "hybrid";
+    provider: string | null;
+    runId: string | null;
+    status: ChatLaunchStatus;
+    blockedReason: string | null;
+    warnings: string[];
+    requestedAt: string;
+    updatedAt: string;
+    metadata: Record<string, unknown>;
+};
+export type ChatThreadRecord = {
+    id: string;
+    commandCenterId: string | null;
+    initiativeId: string | null;
+    initiativeTitle: string | null;
+    workstreamId: string | null;
+    taskId: string | null;
+    title: string;
+    summary: string | null;
+    status: ChatThreadStatus;
+    assigneeId: string | null;
+    assigneeName: string | null;
+    watcherIds: string[];
+    watcherNames: string[];
+    messageCount: number;
+    launchCount: number;
+    lastMessageAt: string | null;
+    lastLaunchAt: string | null;
+    lastActivityAt: string;
+    lastSnippet: string | null;
+    createdAt: string;
+    updatedAt: string;
+    messages: ChatMessageRecord[];
+    launches: ChatLaunchAttemptRecord[];
+    metadata: Record<string, unknown>;
+};
+export type ChatThreadSummary = Omit<ChatThreadRecord, "messages" | "launches"> & {
+    latestMessage: ChatMessageRecord | null;
+    latestLaunch: ChatLaunchAttemptRecord | null;
+};
+export declare function listChatThreads(input?: {
+    commandCenterId?: string | null;
+    initiativeId?: string | null;
+    query?: string | null;
+    status?: string | null;
+    limit?: number;
+    offset?: number;
+}): {
+    threads: ChatThreadSummary[];
+    total: number;
+    updatedAt: string;
+};
+export declare function getChatThread(threadId: string): ChatThreadRecord | null;
+export declare function sendChatMessage(input: {
+    threadId?: string | null;
+    commandCenterId?: string | null;
+    initiativeId?: string | null;
+    initiativeTitle?: string | null;
+    workstreamId?: string | null;
+    taskId?: string | null;
+    title?: string | null;
+    body: string;
+    role?: ChatMessageRole;
+    senderId?: string | null;
+    senderName?: string | null;
+    assigneeId?: string | null;
+    assigneeName?: string | null;
+    watcherIds?: string[];
+    watcherNames?: string[];
+    attachments?: Array<Partial<ChatAttachmentRecord> & {
+        name?: string | null;
+    }>;
+    metadata?: Record<string, unknown>;
+}): {
+    thread: ChatThreadRecord;
+    message: ChatMessageRecord;
+    createdThread: boolean;
+    updatedAt: string;
+};
+export declare function recordChatLaunch(input: {
+    threadId: string;
+    messageId: string;
+    assigneeId?: string | null;
+    assigneeName?: string | null;
+    watcherIds?: string[];
+    watcherNames?: string[];
+    executionMode?: "local_queue" | "cloud" | "hybrid";
+    provider?: string | null;
+    runId?: string | null;
+    status?: ChatLaunchStatus;
+    blockedReason?: string | null;
+    warnings?: string[];
+    metadata?: Record<string, unknown>;
+}): {
+    thread: ChatThreadRecord;
+    launch: ChatLaunchAttemptRecord;
+    updatedAt: string;
+};
+export declare function updateChatLaunchStatus(input: {
+    threadId: string;
+    launchId: string;
+    status: ChatLaunchStatus;
+    runId?: string | null;
+    blockedReason?: string | null;
+    warnings?: string[];
+}): {
+    thread: ChatThreadRecord;
+    launch: ChatLaunchAttemptRecord;
+    updatedAt: string;
+};
+export declare function linkChatThreadScope(input: {
+    threadId: string;
+    commandCenterId?: string | null;
+    initiativeId?: string | null;
+    initiativeTitle?: string | null;
+    workstreamId?: string | null;
+    taskId?: string | null;
+}): {
+    thread: ChatThreadRecord;
+    eventMessage: ChatMessageRecord;
+    updatedAt: string;
+};