@useorgx/openclaw-plugin 0.4.9 → 0.7.2

package/dist/http/helpers/dispatch-lifecycle.js

@@ -1,8 +1,65 @@
 import { appendToOutbox } from "../../outbox.js";
 import { computeMilestoneRollup, computeWorkstreamRollup, } from "../../reporting/rollups.js";
 import { readSkillPackState } from "../../skill-pack-state.js";
+import { normalizeDecisionActionType } from "../../contracts/shared-types.js";
 import { buildMissionControlGraph, deriveExecutionPolicy, inferExecutionDomainFromText, normalizeExecutionDomain, ORGX_SKILL_BY_DOMAIN, spawnGuardIsRateLimited, summarizeSpawnGuardBlockReason, } from "./mission-control.js";
 export function createDispatchLifecycle(deps) {
+    const decisionV2Enabled = String(process.env.DECISION_V2_ENABLED ?? "true").trim().toLowerCase() !== "false";
+    const decisionDedupeEnabled = String(process.env.DECISION_DEDUPE_ENABLED ?? "true").trim().toLowerCase() !== "false";
+    const decisionEvidenceRequiredForBlocking = String(process.env.DECISION_EVIDENCE_REQUIRED_FOR_BLOCKING ?? "false")
+        .trim()
+        .toLowerCase() === "true";
+    const asRecord = (value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return null;
+        return value;
+    };
+    const extractDecisionIdsFromChangesetResults = (value) => {
+        if (!Array.isArray(value))
+            return [];
+        const ids = [];
+        const seen = new Set();
+        const pushId = (candidate) => {
+            if (typeof candidate !== "string")
+                return;
+            const id = candidate.trim();
+            if (!id || seen.has(id))
+                return;
+            seen.add(id);
+            ids.push(id);
+        };
+        for (const entry of value) {
+            const record = asRecord(entry);
+            if (!record)
+                continue;
+            pushId(record.decision_id);
+            pushId(record.decisionId);
+            const directDecision = asRecord(record.decision);
+            if (directDecision) {
+                pushId(directDecision.id);
+                pushId(directDecision.decision_id);
+                pushId(directDecision.decisionId);
+            }
+            const entityType = (typeof record.entity_type === "string" ? record.entity_type : null) ??
+                (typeof record.entityType === "string" ? record.entityType : null);
+            if (entityType && entityType.trim().toLowerCase() === "decision") {
+                pushId(record.entity_id);
+                pushId(record.entityId);
+                pushId(record.id);
+            }
+            const created = asRecord(record.created);
+            if (created) {
+                const createdType = (typeof created.entity_type === "string" ? created.entity_type : null) ??
+                    (typeof created.entityType === "string" ? created.entityType : null);
+                if (createdType && createdType.trim().toLowerCase() === "decision") {
+                    pushId(created.entity_id);
+                    pushId(created.entityId);
+                    pushId(created.id);
+                }
+            }
+        }
+        return ids;
+    };
     function withProvenanceMetadata(metadata) {
         const input = metadata ?? {};
         const out = { ...input };
@@ -62,6 +119,14 @@ export function createDispatchLifecycle(deps) {
         const message = input.message.trim();
         if (!message)
             return;
+        const normalizedRunId = input.runId?.trim() || null;
+        const normalizedCorrelationId = normalizedRunId ? null : (input.correlationId?.trim() || `openclaw-${Date.now()}`);
+        const canonicalMetadata = {
+            initiative_id: initiativeId,
+            run_id: normalizedRunId,
+            slice_run_id: normalizedRunId,
+            correlation_id: normalizedCorrelationId,
+        };
         const metadataWithProvenance = withProvenanceMetadata(input.metadata);
         const activityBucket = deps.deriveStructuredActivityBucket({
             phase: input.phase,
@@ -70,15 +135,14 @@ export function createDispatchLifecycle(deps) {
         });
         const enrichedMetadata = {
             ...(metadataWithProvenance ?? {}),
+            ...canonicalMetadata,
             activity_bucket: activityBucket,
         };
         try {
             await deps.client.emitActivity({
                 initiative_id: initiativeId,
-                run_id: input.runId ?? undefined,
-                correlation_id: input.runId
-                    ? undefined
-                    : (input.correlationId?.trim() || `openclaw-${Date.now()}`),
+                run_id: normalizedRunId ?? undefined,
+                correlation_id: normalizedCorrelationId ?? undefined,
                 source_client: "openclaw",
                 message,
                 phase: input.phase,
@@ -92,7 +156,7 @@ export function createDispatchLifecycle(deps) {
         }
         catch (err) {
             const msg = deps.safeErrorMessage(err);
-            const runId = input.runId?.trim() || "";
+            const runId = normalizedRunId ?? "";
             // If OrgX rejects an unknown run_id, retry by treating the local run_id as a
             // correlation key (non-UUID) so OrgX can create/attach a run deterministically.
             if (runId && /^404\b/.test(msg) && /\brun\b/i.test(msg) && /not found/i.test(msg)) {
@@ -124,9 +188,7 @@ export function createDispatchLifecycle(deps) {
             // Fall back to local outbox so activity is still visible in Mission Control/Activity.
             try {
                 const timestamp = new Date().toISOString();
-                const runId = input.runId?.trim() ||
-                    input.correlationId?.trim() ||
-                    null;
+                const runId = normalizedRunId || normalizedCorrelationId || null;
                 const activityItem = {
                     id: deps.randomUUID(),
                     type: input.phase === "completed"
@@ -167,10 +229,8 @@ export function createDispatchLifecycle(deps) {
                     timestamp,
                     payload: {
                         initiative_id: initiativeId,
-                        run_id: input.runId?.trim() || undefined,
-                        correlation_id: input.runId
-                            ? undefined
-                            : (input.correlationId?.trim() || `openclaw-${Date.now()}`),
+                        run_id: normalizedRunId ?? undefined,
+                        correlation_id: normalizedCorrelationId ?? undefined,
                         source_client: "openclaw",
                         message,
                         phase: input.phase,
@@ -192,10 +252,124 @@ export function createDispatchLifecycle(deps) {
     async function requestDecisionSafe(input) {
         const initiativeId = input.initiativeId?.trim() ?? "";
         const title = input.title.trim();
-        if (!initiativeId || !title)
-            return;
+        if (!initiativeId || !title) {
+            return { queued: false, decisionIds: [] };
+        }
+        const normalizedOptions = [];
+        for (const entry of Array.isArray(input.options) ? input.options : []) {
+            if (typeof entry === "string") {
+                const label = entry.trim();
+                if (label.length > 0)
+                    normalizedOptions.push(label);
+                continue;
+            }
+            if (!entry || typeof entry !== "object" || Array.isArray(entry))
+                continue;
+            const record = entry;
+            const label = typeof record.label === "string" ? record.label.trim() : "";
+            if (!label)
+                continue;
+            const optionPayload = {
+                label,
+            };
+            if (typeof record.id === "string" && record.id.trim()) {
+                optionPayload.id = record.id.trim();
+            }
+            if (typeof record.description === "string" && record.description.trim()) {
+                optionPayload.description = record.description.trim();
+            }
+            if (typeof record.implied_status === "string" && record.implied_status.trim()) {
+                const implied = record.implied_status.trim().toLowerCase();
+                if (implied === "approved" ||
+                    implied === "declined" ||
+                    implied === "cancelled" ||
+                    implied === "rejected") {
+                    optionPayload.implied_status = implied;
+                }
+            }
+            const normalizedActionType = normalizeDecisionActionType(record.action_type ?? record.type ?? record.verb ?? record.action);
+            if (normalizedActionType) {
+                optionPayload.action_type = normalizedActionType;
+            }
+            if (record.requires_note === true) {
+                optionPayload.requires_note = true;
+            }
+            normalizedOptions.push(optionPayload);
+        }
+        const normalizedEvidenceRefs = (Array.isArray(input.evidenceRefs) ? input.evidenceRefs : [])
+            .map((entry) => (entry && typeof entry === "object" && !Array.isArray(entry) ? entry : null))
+            .filter((entry) => Boolean(entry));
+        const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+        const asUuid = (value) => {
+            const normalized = value?.trim() ?? "";
+            return uuidPattern.test(normalized) ? normalized : undefined;
+        };
+        const asIsoDateTime = (value) => {
+            const normalized = value?.trim() ?? "";
+            if (!normalized)
+                return undefined;
+            const epoch = Date.parse(normalized);
+            if (!Number.isFinite(epoch))
+                return undefined;
+            return new Date(epoch).toISOString();
+        };
+        const sourceRef = input.sourceRef && typeof input.sourceRef === "object" && !Array.isArray(input.sourceRef)
+            ? input.sourceRef
+            : null;
+        const metadata = input.metadata && typeof input.metadata === "object" && !Array.isArray(input.metadata)
+            ? input.metadata
+            : null;
+        const dedupeKey = input.dedupeKey?.trim() ||
+            `decision:${deps.stableHash([
+                initiativeId,
+                input.workstreamId?.trim() || "none",
+                input.conflictSource?.trim() || "general",
+                title.toLowerCase(),
+            ].join("|")).slice(0, 24)}`;
+        const blocking = input.blocking ?? true;
+        const fallbackEvidenceRefs = blocking && decisionEvidenceRequiredForBlocking && normalizedEvidenceRefs.length === 0
+            ? [
+                {
+                    evidence_type: "decision_context",
+                    title: "Decision context",
+                    summary: input.summary?.trim() ||
+                        "Blocking decision emitted without explicit evidence payload.",
+                    payload: {
+                        source_ref: sourceRef ?? null,
+                        generated_by: "plugin_guardrail",
+                    },
+                },
+            ]
+            : [];
+        const effectiveEvidenceRefs = [...normalizedEvidenceRefs, ...fallbackEvidenceRefs];
+        const operation = {
+            op: "decision.create",
+            title,
+            summary: input.summary ?? undefined,
+            urgency: input.urgency ?? "high",
+            options: normalizedOptions,
+            blocking,
+            ...(decisionV2Enabled
+                ? {
+                    decision_type: input.decisionType?.trim() || undefined,
+                    workstream_id: asUuid(input.workstreamId),
+                    agent_id: asUuid(input.agentId),
+                    due_at: asIsoDateTime(input.dueAt),
+                    source_system: input.sourceSystem?.trim() || "openclaw",
+                    conflict_source: input.conflictSource?.trim() || undefined,
+                    dedupe_key: decisionDedupeEnabled ? dedupeKey : undefined,
+                    recommended_action: input.recommendedAction?.trim() || undefined,
+                    source_run_id: asUuid(input.sourceRunId),
+                    source_session_id: input.sourceSessionId?.trim() || undefined,
+                    source_stream_id: asUuid(input.sourceStreamId),
+                    source_ref: sourceRef ?? undefined,
+                    evidence_refs: effectiveEvidenceRefs.length > 0 ? effectiveEvidenceRefs : undefined,
+                    metadata: metadata ?? undefined,
+                }
+                : {}),
+        };
         try {
-            await deps.client.applyChangeset({
+            const response = await deps.client.applyChangeset({
                 initiative_id: initiativeId,
                 correlation_id: input.correlationId?.trim() || undefined,
                 source_client: "openclaw",
@@ -203,34 +377,21 @@ export function createDispatchLifecycle(deps) {
                     "openclaw",
                     "decision",
                     initiativeId,
+                    dedupeKey,
                     title,
                     input.correlationId ?? null,
                 ]),
-                operations: [
-                    {
-                        op: "decision.create",
-                        title,
-                        summary: input.summary ?? undefined,
-                        urgency: input.urgency ?? "high",
-                        options: input.options ?? [],
-                        blocking: input.blocking ?? true,
-                    },
-                ],
+                operations: [operation],
             });
+            return {
+                queued: true,
+                decisionIds: extractDecisionIdsFromChangesetResults(response?.results),
+            };
         }
         catch (err) {
             const timestamp = new Date().toISOString();
             const correlationId = input.correlationId?.trim() || undefined;
-            const operations = [
-                {
-                    op: "decision.create",
-                    title,
-                    summary: input.summary ?? undefined,
-                    urgency: input.urgency ?? "high",
-                    options: input.options ?? [],
-                    blocking: input.blocking ?? true,
-                },
-            ];
+            const operations = [operation];
             const activityItem = {
                 id: deps.randomUUID(),
                 type: "decision_requested",
@@ -252,7 +413,17 @@ export function createDispatchLifecycle(deps) {
                     event: "decision_buffered",
                     urgency: input.urgency ?? "high",
                     blocking: input.blocking ?? true,
-                    options: input.options ?? [],
+                    options: normalizedOptions,
+                    dedupe_key: decisionDedupeEnabled ? dedupeKey : null,
+                    decision_type: decisionV2Enabled
+                        ? input.decisionType?.trim() || null
+                        : null,
+                    conflict_source: decisionV2Enabled
+                        ? input.conflictSource?.trim() || null
+                        : null,
+                    source_system: decisionV2Enabled
+                        ? input.sourceSystem?.trim() || "openclaw"
+                        : "openclaw",
                     error: deps.safeErrorMessage(err),
                 },
             };
@@ -269,6 +440,7 @@ export function createDispatchLifecycle(deps) {
                             "openclaw",
                             "decision",
                             initiativeId,
+                            dedupeKey,
                             title,
                             input.correlationId ?? null,
                             "outbox",
@@ -277,9 +449,10 @@ export function createDispatchLifecycle(deps) {
                     },
                     activityItem,
                 });
+                return { queued: true, decisionIds: [] };
             }
             catch {
-                // best effort
+                return { queued: false, decisionIds: [] };
             }
         }
     }
@@ -581,6 +754,38 @@ export function createDispatchLifecycle(deps) {
                     "Pause and investigate quality gate",
                 ],
                 blocking: true,
+                decisionType: "spawn_guard_blocked",
+                workstreamId: workstreamId || null,
+                agentId: input.agentId ?? null,
+                sourceSystem: "openclaw",
+                conflictSource: "spawn_guard_blocked",
+                dedupeKey: [
+                    "dispatch",
+                    input.initiativeId ?? "none",
+                    workstreamId || "none",
+                    taskId || "none",
+                    "spawn_guard_blocked",
+                ].join(":"),
+                recommendedAction: "Choose exception, reassignment, or pause before retrying dispatch.",
+                sourceRunId: input.runId ?? null,
+                sourceRef: {
+                    run_id: input.runId ?? null,
+                    correlation_id: input.correlationId,
+                    task_id: taskId || null,
+                    workstream_id: workstreamId || null,
+                    domain: input.executionPolicy.domain,
+                },
+                evidenceRefs: [
+                    {
+                        evidence_type: "spawn_guard_result",
+                        title: `Spawn guard blocked ${targetLabel}`,
+                        summary: blockedReason,
+                        payload: {
+                            spawn_guard: spawnGuardResult,
+                            required_skills: input.executionPolicy.requiredSkills,
+                        },
+                    },
+                ],
             });
         }
         return {

package/dist/http/helpers/kickoff-context.js

@@ -56,6 +56,61 @@ export function renderKickoffMessage(input) {
     const allow = normalizeKickoffLines(kickoff.tool_scope?.allow ?? null);
     const deny = normalizeKickoffLines(kickoff.tool_scope?.deny ?? null);
     const toolNotes = (kickoff.tool_scope?.notes ?? "").trim();
+    const personaVoice = (kickoff.persona?.voice ?? "").trim();
+    const collaborationStyle = (kickoff.persona?.collaboration_style ?? "").trim();
+    const personaDefaults = normalizeKickoffLines(kickoff.persona?.defaults ?? null);
+    const runtimeSettings = kickoff.runtime_settings && typeof kickoff.runtime_settings === "object"
+        ? kickoff.runtime_settings
+        : null;
+    const customRunInstructions = runtimeSettings && typeof runtimeSettings.custom_run_instructions === "string"
+        ? runtimeSettings.custom_run_instructions.trim()
+        : "";
+    const runtimeFlagLines = [
+        runtimeSettings && typeof runtimeSettings.decision_v2_enabled === "boolean"
+            ? `- Decision V2: ${runtimeSettings.decision_v2_enabled ? "enabled" : "disabled"}`
+            : null,
+        runtimeSettings && typeof runtimeSettings.decision_dedupe_enabled === "boolean"
+            ? `- Decision dedupe: ${runtimeSettings.decision_dedupe_enabled ? "enabled" : "disabled"}`
+            : null,
+        runtimeSettings &&
+            typeof runtimeSettings.decision_evidence_required_for_blocking === "boolean"
+            ? `- Blocking evidence required: ${runtimeSettings.decision_evidence_required_for_blocking ? "enabled" : "disabled"}`
+            : null,
+        runtimeSettings &&
+            typeof runtimeSettings.decision_auto_resolve_guarded_enabled === "boolean"
+            ? `- Guarded auto-resolve: ${runtimeSettings.decision_auto_resolve_guarded_enabled ? "enabled" : "disabled"}`
+            : null,
+        runtimeSettings &&
+            typeof runtimeSettings.question_auto_answer_enabled === "boolean"
+            ? `- Question auto-answer: ${runtimeSettings.question_auto_answer_enabled ? "enabled" : "disabled"}`
+            : null,
+        runtimeSettings &&
+            typeof runtimeSettings.question_auto_answer_timeout_sec === "number"
+            ? `- Question auto-answer timeout: ${Math.max(10, Math.min(3600, Math.floor(runtimeSettings.question_auto_answer_timeout_sec)))}s`
+            : runtimeSettings &&
+                typeof runtimeSettings.question_auto_answer_delay_seconds === "number"
+                ? `- Question auto-answer delay: ${Math.max(1, Math.min(900, Math.floor(runtimeSettings.question_auto_answer_delay_seconds)))}s`
+                : null,
+        runtimeSettings &&
+            typeof runtimeSettings.question_auto_answer_policy === "string"
+            ? `- Question auto-answer policy: ${runtimeSettings.question_auto_answer_policy}`
+            : null,
+        runtimeSettings &&
+            typeof runtimeSettings.question_blocking_behavior === "string"
+            ? `- Blocking question behavior: ${runtimeSettings.question_blocking_behavior}`
+            : null,
+        runtimeSettings &&
+            typeof runtimeSettings.question_auto_answer_action === "string"
+            ? `- Question auto-answer action: ${runtimeSettings.question_auto_answer_action.trim().toLowerCase() === "reject"
+                ? "reject"
+                : "approve"}`
+            : null,
+        runtimeSettings &&
+            runtimeSettings.workspace_question_defaults &&
+            typeof runtimeSettings.workspace_question_defaults === "object"
+            ? "- Workspace question defaults available"
+            : null,
+    ].filter((line) => Boolean(line));
     const contextHash = kickoff.context_hash?.trim() || null;
     const schemaVersion = (kickoff.schema_version ?? "").trim();
     const lines = [];
@@ -123,6 +178,26 @@ export function renderKickoffMessage(input) {
     lines.push("- Communicate early when blocked. Provide options, tradeoffs, and a recommendation.");
     lines.push("- Verify before claiming done. Prefer proof (commands/tests) over confidence.");
     lines.push("");
+    if (runtimeFlagLines.length > 0 || customRunInstructions) {
+        lines.push("## Runtime Settings");
+        for (const line of runtimeFlagLines)
+            lines.push(line);
+        if (customRunInstructions) {
+            lines.push("- Custom run instructions:");
+            lines.push(`  ${customRunInstructions}`);
+        }
+        lines.push("");
+    }
+    if (personaVoice || collaborationStyle || personaDefaults.length > 0) {
+        lines.push("## Behavior");
+        if (personaVoice)
+            lines.push(`- Voice: ${personaVoice}`);
+        if (collaborationStyle)
+            lines.push(`- Collaboration style: ${collaborationStyle}`);
+        for (const item of personaDefaults)
+            lines.push(`- Default: ${item}`);
+        lines.push("");
+    }
     if (allow.length > 0 || deny.length > 0 || toolNotes) {
         lines.push("## Tool Scope");
         if (allow.length > 0)
@@ -139,6 +214,35 @@ export function renderKickoffMessage(input) {
             lines.push(`- ${item}`);
         lines.push("");
     }
+    const teamContext = kickoff.team_context;
+    if (teamContext) {
+        const completions = Array.isArray(teamContext.recent_completions)
+            ? teamContext.recent_completions.slice(0, 5)
+            : [];
+        const teamDecisions = Array.isArray(teamContext.recent_decisions)
+            ? teamContext.recent_decisions.slice(0, 3)
+            : [];
+        if (completions.length > 0 || teamDecisions.length > 0) {
+            lines.push("## Team Activity");
+            lines.push("Recent work by other agents (for awareness, not direct action):");
+            for (const c of completions) {
+                const outputs = Array.isArray(c.key_outputs) && c.key_outputs.length > 0
+                    ? ` (${c.key_outputs.join(", ")})`
+                    : "";
+                lines.push(`- [${c.domain}] ${c.task_title}: ${c.summary}${outputs}`);
+            }
+            if (teamDecisions.length > 0) {
+                lines.push("");
+                lines.push("Recent decisions:");
+                for (const d of teamDecisions) {
+                    lines.push(`- ${d.title}: ${d.resolution}`);
+                }
+            }
+            lines.push("");
+            lines.push("Reference naturally when relevant. Do not summarize back.");
+            lines.push("");
+        }
+    }
     if (contextHash || schemaVersion) {
         lines.push("## Provenance");
         if (schemaVersion)

package/dist/http/helpers/llm-client.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared LLM client for classification, summarization, and generation tasks.
+ *
+ * Generalizes the pattern from activity-headline.ts into a reusable client
+ * with in-memory caching, timeout, and heuristic fallback.
+ */
+export type LlmSource = "llm" | "heuristic";
+export interface LlmRequest {
+    /** Namespace for cache keys (e.g. "retro", "turn_summary", "classify_status") */
+    taskId: string;
+    systemPrompt: string;
+    userPrompt: string;
+    /** Override default model. Use DEFAULT_GENERATION_MODEL for longer outputs. */
+    model?: string;
+    /** Default 0.1 */
+    temperature?: number;
+    /** Default 128 */
+    maxTokens?: number;
+    /** Default 4000ms */
+    timeoutMs?: number;
+    /** Default 12h. Set 0 to disable caching. */
+    cacheTtlMs?: number;
+}
+export interface LlmResponse<T> {
+    result: T;
+    source: LlmSource;
+    model: string | null;
+}
+export declare function resolveApiKey(): string | null;
+/** Reset cached key (for testing or key rotation). */
+export declare function resetApiKeyCache(): void;
+/**
+ * Call LLM for a text completion with automatic caching and heuristic fallback.
+ *
+ * @param request - The LLM request configuration
+ * @param fallback - Heuristic fallback that produces a result when LLM is unavailable
+ * @param parse - Optional transform on the raw LLM text (default: identity)
+ */
+export declare function callLlm(request: LlmRequest, fallback: () => string, parse?: (raw: string) => string | null): Promise<LlmResponse<string>>;
+/**
+ * Call LLM expecting a JSON response. Parses and validates via the provided parser.
+ *
+ * @param request - The LLM request (systemPrompt should instruct JSON output)
+ * @param parse - Parse raw JSON string into typed result, return null on failure
+ * @param fallback - Heuristic fallback
+ */
+export declare function callLlmJson<T>(request: LlmRequest, parse: (raw: string) => T | null, fallback: () => T): Promise<LlmResponse<T>>;