@useorgx/openclaw-plugin 0.4.8 → 0.4.9

package/dist/sync/outbox-replay.js

@@ -0,0 +1,514 @@
+import { registerArtifact } from "../artifacts/register-artifact.js";
+import { readOutbox, readOutboxSummary, replaceOutbox } from "../outbox.js";
+import { extractProgressOutboxMessage } from "../reporting/outbox-replay.js";
+export function createOutboxReplayer(deps) {
+    const { client, logger, toErrorMessage, stableHash, resolveReportingContext, pickStringField, pickStringArrayField, toReportingPhase, parseRetroEntityType, isUuid, } = deps;
+    async function replayOutboxEvent(event) {
+        const payload = event.payload ?? {};
+        function normalizeRunFields(context) {
+            // We prefer correlation IDs for replay because many local adapters use UUID-like
+            // session IDs that do *not* exist as server-side run IDs.
+            if (context.correlationId) {
+                return { run_id: undefined, correlation_id: context.correlationId };
+            }
+            if (context.runId) {
+                return {
+                    run_id: undefined,
+                    correlation_id: `openclaw_run_${stableHash(context.runId).slice(0, 24)}`,
+                };
+            }
+            return { run_id: undefined, correlation_id: undefined };
+        }
+        if (event.type === "progress") {
+            const message = extractProgressOutboxMessage(payload);
+            if (!message) {
+                logger.warn?.("[orgx] Dropping invalid progress outbox event", {
+                    eventId: event.id,
+                });
+                return;
+            }
+            const context = resolveReportingContext(payload);
+            if (!context.ok) {
+                throw new Error(context.error);
+            }
+            const rawPhase = pickStringField(payload, "phase") ?? "implementing";
+            const progressPct = typeof payload.progress_pct === "number"
+                ? payload.progress_pct
+                : typeof payload.progressPct === "number"
+                    ? payload.progressPct
+                    : undefined;
+            const phase = rawPhase === "intent" ||
+                rawPhase === "execution" ||
+                rawPhase === "blocked" ||
+                rawPhase === "review" ||
+                rawPhase === "handoff" ||
+                rawPhase === "completed"
+                ? rawPhase
+                : toReportingPhase(rawPhase, progressPct);
+            const metaRaw = payload.metadata;
+            const meta = metaRaw && typeof metaRaw === "object" && !Array.isArray(metaRaw)
+                ? metaRaw
+                : {};
+            const baseMetadata = {
+                ...meta,
+                source: "orgx_openclaw_outbox_replay",
+                outbox_event_id: event.id,
+            };
+            let emitPayload = {
+                initiative_id: context.value.initiativeId,
+                run_id: context.value.runId,
+                correlation_id: context.value.correlationId,
+                source_client: context.value.sourceClient,
+                message,
+                phase,
+                progress_pct: progressPct,
+                level: pickStringField(payload, "level"),
+                next_step: pickStringField(payload, "next_step") ??
+                    pickStringField(payload, "nextStep") ??
+                    undefined,
+                metadata: baseMetadata,
+            };
+            // Locally-buffered progress events often store a local UUID in run_id. OrgX may reject
+            // unknown run IDs on replay; prefer a deterministic non-UUID correlation key instead.
+            if (emitPayload.run_id && !emitPayload.correlation_id) {
+                const replayCorrelationId = `openclaw_run_${stableHash(emitPayload.run_id).slice(0, 24)}`;
+                emitPayload = {
+                    ...emitPayload,
+                    run_id: undefined,
+                    correlation_id: replayCorrelationId,
+                    metadata: {
+                        ...(emitPayload.metadata ?? {}),
+                        replay_run_id_as_correlation: true,
+                    },
+                };
+            }
+            try {
+                await client.emitActivity(emitPayload);
+            }
+            catch (err) {
+                // Some locally-buffered events carry a UUID that *looks* like an OrgX run_id
+                // but was only ever used as a local correlation/grouping key. If OrgX
+                // doesn't recognize it, retry by treating it as correlation_id so OrgX can
+                // create/attach a run deterministically.
+                const msg = toErrorMessage(err);
+                if (emitPayload.run_id &&
+                    /^404\\b/.test(msg) &&
+                    /\\brun\\b/i.test(msg) &&
+                    /not found/i.test(msg)) {
+                    const replayCorrelationId = `openclaw_run_${stableHash(emitPayload.run_id).slice(0, 24)}`;
+                    await client.emitActivity({
+                        ...emitPayload,
+                        run_id: undefined,
+                        correlation_id: replayCorrelationId,
+                        metadata: {
+                            ...(emitPayload.metadata ?? {}),
+                            replay_run_id_as_correlation: true,
+                        },
+                    });
+                }
+                else {
+                    throw err;
+                }
+            }
+            return;
+        }
+        if (event.type === "decision") {
+            const question = pickStringField(payload, "question");
+            if (!question) {
+                logger.warn?.("[orgx] Dropping invalid decision outbox event", {
+                    eventId: event.id,
+                });
+                return;
+            }
+            const context = resolveReportingContext(payload);
+            if (!context.ok) {
+                throw new Error(context.error);
+            }
+            const runFields = normalizeRunFields({
+                runId: context.value.runId,
+                correlationId: context.value.correlationId,
+            });
+            // Payloads should include a stable idempotency_key when enqueued, but older
+            // events may not. Derive a deterministic fallback so outbox replay won't
+            // double-create the same remote decision.
+            const fallbackKey = stableHash(JSON.stringify({
+                t: "decision",
+                initiative_id: context.value.initiativeId,
+                run_id: context.value.runId ?? null,
+                correlation_id: context.value.correlationId ?? null,
+                question,
+            })).slice(0, 24);
+            const resolvedIdempotencyKey = pickStringField(payload, "idempotency_key") ??
+                pickStringField(payload, "idempotencyKey") ??
+                `openclaw:decision:${fallbackKey}`;
+            await client.applyChangeset({
+                initiative_id: context.value.initiativeId,
+                run_id: runFields.run_id,
+                correlation_id: runFields.correlation_id,
+                source_client: context.value.sourceClient,
+                idempotency_key: resolvedIdempotencyKey,
+                operations: [
+                    {
+                        op: "decision.create",
+                        title: question,
+                        summary: pickStringField(payload, "context") ?? undefined,
+                        urgency: pickStringField(payload, "urgency") ?? "medium",
+                        options: pickStringArrayField(payload, "options"),
+                        blocking: typeof payload.blocking === "boolean" ? payload.blocking : true,
+                    },
+                ],
+            });
+            return;
+        }
+        if (event.type === "changeset") {
+            const context = resolveReportingContext(payload);
+            if (!context.ok) {
+                throw new Error(context.error);
+            }
+            const runFields = normalizeRunFields({
+                runId: context.value.runId,
+                correlationId: context.value.correlationId,
+            });
+            const operations = Array.isArray(payload.operations)
+                ? payload.operations
+                : [];
+            if (operations.length === 0) {
+                logger.warn?.("[orgx] Dropping invalid changeset outbox event", {
+                    eventId: event.id,
+                });
+                return;
+            }
+            // Status updates are the most common offline replay payload, and `updateEntity`
+            // is the most widely supported primitive across OrgX deployments. Prefer it
+            // when the changeset contains only simple status mutations.
+            const statusOps = operations
+                .map((op) => {
+                if (!op || typeof op !== "object")
+                    return null;
+                const record = op;
+                const kind = typeof record.op === "string" ? record.op.trim() : "";
+                if (kind === "task.update") {
+                    const taskId = typeof record.task_id === "string" ? record.task_id.trim() : "";
+                    const statusRaw = typeof record.status === "string" ? record.status.trim() : "";
+                    const normalized = statusRaw.toLowerCase().replace(/\s+/g, "_");
+                    const status = normalized === "completed" || normalized === "complete" || normalized === "finished"
+                        ? "done"
+                        : normalized === "inprogress"
+                            ? "in_progress"
+                            : normalized;
+                    if (!taskId || !status)
+                        return null;
+                    return { type: "task", id: taskId, status };
+                }
+                if (kind === "milestone.update") {
+                    const milestoneId = typeof record.milestone_id === "string" ? record.milestone_id.trim() : "";
+                    const statusRaw = typeof record.status === "string" ? record.status.trim() : "";
+                    const normalized = statusRaw.toLowerCase().replace(/\s+/g, "_");
+                    const status = normalized === "done" || normalized === "complete" || normalized === "finished"
+                        ? "completed"
+                        : normalized === "inprogress"
+                            ? "in_progress"
+                            : normalized === "todo" || normalized === "not_started" || normalized === "pending"
+                                ? "planned"
+                                : normalized === "blocked" || normalized === "stuck"
+                                    ? "at_risk"
+                                    : normalized;
+                    if (!milestoneId || !status)
+                        return null;
+                    return { type: "milestone", id: milestoneId, status };
+                }
+                return null;
+            })
+                .filter((item) => Boolean(item));
+            if (statusOps.length === operations.length) {
+                for (const op of statusOps) {
+                    await client.updateEntity(op.type, op.id, { status: op.status });
+                }
+                return;
+            }
+            // Payloads should include a stable idempotency_key when enqueued, but older
+            // events may not. Derive a deterministic fallback so outbox replay won't
+            // double-create the same remote change.
+            const fallbackKey = stableHash(JSON.stringify({
+                t: "changeset",
+                initiative_id: context.value.initiativeId,
+                run_id: context.value.runId ?? null,
+                correlation_id: context.value.correlationId ?? null,
+                operations,
+            })).slice(0, 24);
+            const resolvedIdempotencyKey = pickStringField(payload, "idempotency_key") ??
+                pickStringField(payload, "idempotencyKey") ??
+                `openclaw:changeset:${fallbackKey}`;
+            await client.applyChangeset({
+                initiative_id: context.value.initiativeId,
+                run_id: runFields.run_id,
+                correlation_id: runFields.correlation_id,
+                source_client: context.value.sourceClient,
+                idempotency_key: resolvedIdempotencyKey,
+                operations,
+            });
+            return;
+        }
+        if (event.type === "outcome") {
+            const context = resolveReportingContext(payload);
+            if (!context.ok) {
+                throw new Error(context.error);
+            }
+            const runFields = normalizeRunFields({
+                runId: context.value.runId,
+                correlationId: context.value.correlationId,
+            });
+            const executionId = pickStringField(payload, "execution_id") ??
+                pickStringField(payload, "executionId");
+            const executionType = pickStringField(payload, "execution_type") ??
+                pickStringField(payload, "executionType");
+            const agentId = pickStringField(payload, "agent_id") ??
+                pickStringField(payload, "agentId");
+            const success = typeof payload.success === "boolean"
+                ? payload.success
+                : null;
+            if (!executionId || !executionType || !agentId || success === null) {
+                logger.warn?.("[orgx] Dropping invalid outcome outbox event", {
+                    eventId: event.id,
+                });
+                return;
+            }
+            const metaRaw = payload.metadata;
+            const meta = metaRaw && typeof metaRaw === "object" && !Array.isArray(metaRaw)
+                ? metaRaw
+                : {};
+            await client.recordRunOutcome({
+                initiative_id: context.value.initiativeId,
+                run_id: runFields.run_id,
+                correlation_id: runFields.correlation_id,
+                source_client: context.value.sourceClient,
+                execution_id: executionId,
+                execution_type: executionType,
+                agent_id: agentId,
+                task_type: pickStringField(payload, "task_type") ??
+                    pickStringField(payload, "taskType") ??
+                    undefined,
+                domain: pickStringField(payload, "domain") ?? undefined,
+                started_at: pickStringField(payload, "started_at") ??
+                    pickStringField(payload, "startedAt") ??
+                    undefined,
+                completed_at: pickStringField(payload, "completed_at") ??
+                    pickStringField(payload, "completedAt") ??
+                    undefined,
+                inputs: payload.inputs && typeof payload.inputs === "object"
+                    ? payload.inputs
+                    : undefined,
+                outputs: payload.outputs && typeof payload.outputs === "object"
+                    ? payload.outputs
+                    : undefined,
+                steps: Array.isArray(payload.steps)
+                    ? payload.steps
+                    : undefined,
+                success,
+                quality_score: typeof payload.quality_score === "number"
+                    ? payload.quality_score
+                    : typeof payload.qualityScore === "number"
+                        ? payload.qualityScore
+                        : undefined,
+                duration_vs_estimate: typeof payload.duration_vs_estimate === "number"
+                    ? payload.duration_vs_estimate
+                    : typeof payload.durationVsEstimate === "number"
+                        ? payload.durationVsEstimate
+                        : undefined,
+                cost_vs_budget: typeof payload.cost_vs_budget === "number"
+                    ? payload.cost_vs_budget
+                    : typeof payload.costVsBudget === "number"
+                        ? payload.costVsBudget
+                        : undefined,
+                human_interventions: typeof payload.human_interventions === "number"
+                    ? payload.human_interventions
+                    : typeof payload.humanInterventions === "number"
+                        ? payload.humanInterventions
+                        : undefined,
+                user_satisfaction: typeof payload.user_satisfaction === "number"
+                    ? payload.user_satisfaction
+                    : typeof payload.userSatisfaction === "number"
+                        ? payload.userSatisfaction
+                        : undefined,
+                errors: Array.isArray(payload.errors)
+                    ? payload.errors.filter((e) => typeof e === "string")
+                    : undefined,
+                metadata: {
+                    ...meta,
+                    source: "orgx_openclaw_outbox_replay",
+                    outbox_event_id: event.id,
+                },
+            });
+            return;
+        }
+        if (event.type === "retro") {
+            const context = resolveReportingContext(payload);
+            if (!context.ok) {
+                throw new Error(context.error);
+            }
+            const runFields = normalizeRunFields({
+                runId: context.value.runId,
+                correlationId: context.value.correlationId,
+            });
+            const retro = payload.retro && typeof payload.retro === "object" && !Array.isArray(payload.retro)
+                ? payload.retro
+                : null;
+            const summary = retro && typeof retro.summary === "string" ? retro.summary.trim() : "";
+            if (!retro || !summary) {
+                logger.warn?.("[orgx] Dropping invalid retro outbox event", {
+                    eventId: event.id,
+                });
+                return;
+            }
+            const entityTypeRaw = pickStringField(payload, "entity_type") ??
+                pickStringField(payload, "entityType");
+            const parsedEntityType = parseRetroEntityType(entityTypeRaw) ?? null;
+            // Server-side enum parity can lag behind local clients. Only attach to the
+            // entity types that are guaranteed to exist today.
+            const entityType = parsedEntityType === "initiative" || parsedEntityType === "task"
+                ? parsedEntityType
+                : null;
+            const entityIdRaw = pickStringField(payload, "entity_id") ??
+                pickStringField(payload, "entityId") ??
+                null;
+            const entityId = isUuid(entityIdRaw ?? undefined) ? entityIdRaw : null;
+            await client.recordRunRetro({
+                initiative_id: context.value.initiativeId,
+                run_id: runFields.run_id,
+                correlation_id: runFields.correlation_id,
+                source_client: context.value.sourceClient,
+                entity_type: entityType && entityId ? entityType : undefined,
+                entity_id: entityType && entityId ? entityId : undefined,
+                title: pickStringField(payload, "title") ?? undefined,
+                idempotency_key: pickStringField(payload, "idempotency_key") ??
+                    pickStringField(payload, "idempotencyKey") ??
+                    undefined,
+                retro: retro,
+                markdown: pickStringField(payload, "markdown") ?? undefined,
+            });
+            return;
+        }
+        if (event.type === "artifact") {
+            // Artifacts are first-class UX loop closure (activity stream + entity modals).
+            // Try to persist upstream; if this fails, keep the event queued for retry.
+            const payload = event.payload && typeof event.payload === "object" && !Array.isArray(event.payload)
+                ? event.payload
+                : {};
+            const name = pickStringField(payload, "name") ?? pickStringField(payload, "title") ?? "";
+            const artifactType = pickStringField(payload, "artifact_type") ?? "other";
+            const entityType = pickStringField(payload, "entity_type") ?? "";
+            const entityId = pickStringField(payload, "entity_id") ?? "";
+            const artifactId = pickStringField(payload, "artifact_id") ?? null;
+            const description = pickStringField(payload, "description") ?? undefined;
+            const externalUrl = pickStringField(payload, "url") ?? pickStringField(payload, "artifact_url") ?? null;
+            const content = pickStringField(payload, "content") ?? pickStringField(payload, "preview_markdown") ?? null;
+            const allowedEntityType = entityType === "initiative" ||
+                entityType === "milestone" ||
+                entityType === "task" ||
+                entityType === "decision" ||
+                entityType === "project"
+                ? entityType
+                : null;
+            if (!allowedEntityType || !entityId.trim() || !name.trim()) {
+                logger.warn?.("[orgx] Dropping invalid artifact outbox event", {
+                    eventId: event.id,
+                    entityType,
+                    entityId,
+                });
+                return;
+            }
+            const result = await registerArtifact(client, client.getBaseUrl(), {
+                artifact_id: artifactId,
+                entity_type: allowedEntityType,
+                entity_id: entityId,
+                name: name.trim(),
+                artifact_type: artifactType.trim() || "other",
+                description,
+                external_url: externalUrl,
+                preview_markdown: content,
+                status: "draft",
+                metadata: {
+                    source: "outbox_replay",
+                    outbox_event_id: event.id,
+                    ...(payload.metadata && typeof payload.metadata === "object" && !Array.isArray(payload.metadata)
+                        ? payload.metadata
+                        : {}),
+                },
+                validate_persistence: process.env.ORGX_VALIDATE_ARTIFACT_PERSISTENCE === "1",
+            });
+            if (!result.ok) {
+                throw new Error(result.persistence.last_error ?? "artifact registration failed");
+            }
+            return;
+        }
+    }
+    async function flushOutboxQueues() {
+        const attemptAt = new Date().toISOString();
+        deps.writeOutboxReplayState({
+            ...deps.readOutboxReplayState(),
+            status: "running",
+            lastReplayAttemptAt: attemptAt,
+            lastReplayError: null,
+        });
+        let hadReplayFailure = false;
+        let lastReplayError = null;
+        // Outbox files are keyed by *session id* (e.g. initiative/run correlation),
+        // not by event type.
+        const outboxSummary = await readOutboxSummary();
+        const queues = Object.entries(outboxSummary.pendingByQueue)
+            .filter(([, count]) => typeof count === "number" && count > 0)
+            .map(([queueId]) => queueId)
+            .sort();
+        for (const queue of queues) {
+            const pending = await readOutbox(queue);
+            if (pending.length === 0) {
+                continue;
+            }
+            const remaining = [];
+            for (const event of pending) {
+                try {
+                    await replayOutboxEvent(event);
+                }
+                catch (err) {
+                    hadReplayFailure = true;
+                    lastReplayError = toErrorMessage(err);
+                    remaining.push(event);
+                    logger.warn?.("[orgx] Outbox replay failed", {
+                        queue,
+                        eventId: event.id,
+                        error: lastReplayError,
+                    });
+                }
+            }
+            await replaceOutbox(queue, remaining);
+            const replayedCount = pending.length - remaining.length;
+            if (replayedCount > 0) {
+                logger.info?.("[orgx] Replayed buffered outbox events", {
+                    queue,
+                    replayed: replayedCount,
+                    remaining: remaining.length,
+                });
+            }
+        }
+        if (hadReplayFailure) {
+            deps.writeOutboxReplayState({
+                ...deps.readOutboxReplayState(),
+                status: "error",
+                lastReplayFailureAt: new Date().toISOString(),
+                lastReplayError,
+            });
+        }
+        else {
+            deps.writeOutboxReplayState({
+                ...deps.readOutboxReplayState(),
+                status: "success",
+                lastReplaySuccessAt: new Date().toISOString(),
+                lastReplayError: null,
+            });
+        }
+    }
+    return {
+        replayOutboxEvent,
+        flushOutboxQueues,
+    };
+}

package/dist/tools/core-tools.d.ts

@@ -0,0 +1,76 @@
+import type { OrgXClient } from "../api.js";
+import type { AutoAssignedAgent } from "../entities/auto-assignment.js";
+import type { RegisteredTool } from "../mcp-http-handler.js";
+import type { OrgSnapshot, ReportingPhase, ReportingSourceClient } from "../types.js";
+export interface ToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}
+export type RegisterToolFn = (tool: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (callId: string, params?: any) => Promise<ToolResult>;
+}, options?: {
+    optional?: boolean;
+}) => void;
+export interface RegisterCoreToolsDeps {
+    registerTool: RegisterToolFn;
+    client: OrgXClient;
+    config: {
+        syncIntervalMs: number;
+        pluginVersion?: string | null;
+    };
+    getCachedSnapshot: () => OrgSnapshot | null;
+    getLastSnapshotAt: () => number;
+    doSync: () => Promise<void>;
+    text: (value: string) => ToolResult;
+    json: (label: string, data: unknown) => ToolResult;
+    formatSnapshot: (snapshot: OrgSnapshot) => string;
+    autoAssignEntityForCreate: (input: {
+        entityType: string;
+        entityId: string;
+        initiativeId: string | null;
+        title: string;
+        summary: string | null;
+    }) => Promise<{
+        updatedEntity?: unknown;
+        assignmentSource: "orchestrator" | "fallback" | "manual";
+        assignedAgents: AutoAssignedAgent[];
+        warnings: string[];
+    }>;
+    toReportingPhase: (phase: string, progressPct?: number) => ReportingPhase;
+    inferReportingInitiativeId: (input: Record<string, unknown>) => string | undefined;
+    isUuid: (value: string | undefined) => value is string;
+    pickNonEmptyString: (...values: Array<unknown>) => string | undefined;
+    resolveReportingContext: (input: Record<string, unknown>) => {
+        ok: true;
+        value: {
+            initiativeId: string;
+            runId?: string;
+            correlationId?: string;
+            sourceClient?: ReportingSourceClient;
+        };
+    } | {
+        ok: false;
+        error: string;
+    };
+    readSkillPackState: () => {
+        pack?: {
+            name?: string | null;
+            version?: string | null;
+            checksum?: string | null;
+        } | null;
+        overrides?: {
+            source?: string | null;
+            name?: string | null;
+            version?: string | null;
+            checksum?: string | null;
+        } | null;
+        etag?: string | null;
+    };
+    randomUUID?: () => string;
+}
+export declare function registerCoreTools(deps: RegisterCoreToolsDeps): Map<string, RegisteredTool>;