@useorgx/openclaw-plugin 0.4.9 → 0.7.0

package/dist/next-up-queue-store.js

@@ -3,6 +3,7 @@ import { getOrgxPluginConfigDir, getOrgxPluginConfigPath } from "./paths.js";
 import { backupCorruptFileSync, writeJsonFileAtomicSync } from "./fs-utils.js";
 import { ensureStoreDirSync, parseJsonSafe, } from "./stores/json-store.js";
 const MAX_PINS = 240;
+const MAX_SUPPRESSIONS = 2_000;
 function storeDir() {
     return getOrgxPluginConfigDir();
 }
@@ -28,31 +29,56 @@ function normalizeEntry(input) {
         updatedAt: input.updatedAt,
     };
 }
+function normalizeSuppression(input) {
+    return {
+        initiativeId: input.initiativeId.trim(),
+        workstreamId: input.workstreamId.trim(),
+        createdAt: input.createdAt,
+        updatedAt: input.updatedAt,
+    };
+}
+function entryKey(input) {
+    return `${input.initiativeId}:${input.workstreamId}`;
+}
+function createEmptyStore() {
+    return {
+        version: 2,
+        updatedAt: new Date().toISOString(),
+        pins: [],
+        suppressions: [],
+    };
+}
 export function readNextUpQueuePins() {
     const file = storeFile();
     try {
         if (!existsSync(file)) {
-            return { version: 1, updatedAt: new Date().toISOString(), pins: [] };
+            return createEmptyStore();
         }
         const raw = readFileSync(file, "utf8");
         const parsed = parseJsonSafe(raw);
         if (!parsed || typeof parsed !== "object") {
             backupCorruptFileSync(file);
-            return { version: 1, updatedAt: new Date().toISOString(), pins: [] };
+            return createEmptyStore();
         }
         const pins = Array.isArray(parsed.pins) ? parsed.pins : [];
+        const suppressions = Array.isArray(parsed.suppressions)
+            ? parsed.suppressions
+            : [];
         return {
-            version: 1,
+            version: 2,
             updatedAt: typeof parsed.updatedAt === "string"
                 ? parsed.updatedAt
                 : new Date().toISOString(),
             pins: pins
                 .filter((entry) => Boolean(entry && typeof entry === "object"))
                 .map((entry) => normalizeEntry(entry)),
+            suppressions: suppressions
+                .filter((entry) => Boolean(entry && typeof entry === "object"))
+                .map((entry) => normalizeSuppression(entry)),
         };
     }
     catch {
-        return { version: 1, updatedAt: new Date().toISOString(), pins: [] };
+        return createEmptyStore();
     }
 }
 export function upsertNextUpQueuePin(input) {
@@ -65,7 +91,7 @@ export function upsertNextUpQueuePin(input) {
     const now = new Date().toISOString();
     const next = readNextUpQueuePins();
     const key = `${initiativeId}:${workstreamId}`;
-    const existing = next.pins.find((pin) => `${pin.initiativeId}:${pin.workstreamId}` === key);
+    const existing = next.pins.find((pin) => entryKey(pin) === key);
     const updated = normalizeEntry({
         initiativeId,
         workstreamId,
@@ -74,7 +100,8 @@ export function upsertNextUpQueuePin(input) {
         createdAt: existing?.createdAt ?? now,
         updatedAt: now,
     });
-    next.pins = [updated, ...next.pins.filter((pin) => `${pin.initiativeId}:${pin.workstreamId}` !== key)].slice(0, MAX_PINS);
+    next.pins = [updated, ...next.pins.filter((pin) => entryKey(pin) !== key)].slice(0, MAX_PINS);
+    next.suppressions = next.suppressions.filter((suppression) => entryKey(suppression) !== key);
     next.updatedAt = now;
     try {
         writeJsonFileAtomicSync(storeFile(), next, 0o600);
@@ -93,7 +120,7 @@ export function removeNextUpQueuePin(input) {
     ensureStoreDir();
     const next = readNextUpQueuePins();
     const key = `${initiativeId}:${workstreamId}`;
-    const filtered = next.pins.filter((pin) => `${pin.initiativeId}:${pin.workstreamId}` !== key);
+    const filtered = next.pins.filter((pin) => entryKey(pin) !== key);
     if (filtered.length === next.pins.length)
         return next;
     next.pins = filtered;
@@ -144,6 +171,9 @@ export function setNextUpQueuePinOrder(input) {
         ordered.push(pin);
     }
     next.pins = ordered.slice(0, MAX_PINS);
+    if (seen.size > 0 && next.suppressions.length > 0) {
+        next.suppressions = next.suppressions.filter((suppression) => !seen.has(entryKey(suppression)));
+    }
     next.updatedAt = now;
     try {
         writeJsonFileAtomicSync(storeFile(), next, 0o600);
@@ -153,3 +183,55 @@ export function setNextUpQueuePinOrder(input) {
     }
     return next;
 }
+export function suppressNextUpQueueItem(input) {
+    const initiativeId = input.initiativeId.trim();
+    const workstreamId = input.workstreamId.trim();
+    if (!initiativeId || !workstreamId) {
+        return readNextUpQueuePins();
+    }
+    ensureStoreDir();
+    const now = new Date().toISOString();
+    const next = readNextUpQueuePins();
+    const key = `${initiativeId}:${workstreamId}`;
+    const existing = next.suppressions.find((suppression) => entryKey(suppression) === key);
+    next.suppressions = [
+        normalizeSuppression({
+            initiativeId,
+            workstreamId,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+        }),
+        ...next.suppressions.filter((suppression) => entryKey(suppression) !== key),
+    ].slice(0, MAX_SUPPRESSIONS);
+    next.pins = next.pins.filter((pin) => entryKey(pin) !== key);
+    next.updatedAt = now;
+    try {
+        writeJsonFileAtomicSync(storeFile(), next, 0o600);
+    }
+    catch {
+        // best effort
+    }
+    return next;
+}
+export function unsuppressNextUpQueueItem(input) {
+    const initiativeId = input.initiativeId.trim();
+    const workstreamId = input.workstreamId.trim();
+    if (!initiativeId || !workstreamId) {
+        return readNextUpQueuePins();
+    }
+    ensureStoreDir();
+    const next = readNextUpQueuePins();
+    const key = `${initiativeId}:${workstreamId}`;
+    const filtered = next.suppressions.filter((suppression) => entryKey(suppression) !== key);
+    if (filtered.length === next.suppressions.length)
+        return next;
+    next.suppressions = filtered;
+    next.updatedAt = new Date().toISOString();
+    try {
+        writeJsonFileAtomicSync(storeFile(), next, 0o600);
+    }
+    catch {
+        // best effort
+    }
+    return next;
+}

package/dist/outbox.d.ts

@@ -11,6 +11,10 @@ export interface OutboxEvent {
     payload: Record<string, unknown>;
     /** Converted to a LiveActivityItem for dashboard display. */
     activityItem: LiveActivityItem;
+    /** Internal replay diagnostics for bounded retry/dead-letter handling. */
+    replayFailures?: number;
+    lastReplayError?: string | null;
+    lastReplayAt?: string | null;
 }
 export interface OutboxSummary {
     pendingTotal: number;
@@ -18,6 +22,7 @@ export interface OutboxSummary {
     oldestEventAt: string | null;
     newestEventAt: string | null;
 }
+export declare function appendOutboxDeadLetter(sessionId: string, event: OutboxEvent, reason: string, error?: string | null): Promise<void>;
 export declare function readOutbox(sessionId: string): Promise<OutboxEvent[]>;
 export declare function appendToOutbox(sessionId: string, event: OutboxEvent): Promise<void>;
 export declare function replaceOutbox(sessionId: string, events: OutboxEvent[]): Promise<void>;

package/dist/outbox.js

@@ -4,8 +4,9 @@
  * Events are flushed on next successful sync.
  */
 import { join } from "node:path";
-import { readFile, writeFile, mkdir, chmod, rename, unlink, readdir, } from "node:fs/promises";
+import { readFile, writeFile, mkdir, chmod, rename, unlink, readdir, appendFile, } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
+import { classifyOutboxReplaySkip } from "./event-sanitization.js";
 import { getOrgxOutboxDir } from "./paths.js";
 function outboxDir() {
     return getOrgxOutboxDir();
@@ -36,6 +37,11 @@ async function hardenPath(path, mode) {
         // best effort
     }
 }
+/** Events older than 7 days are stale — sync will never recover them. */
+const OUTBOX_EVENT_TTL_MS = 7 * 24 * 60 * 60_000;
+/** Hard cap per session to prevent unbounded growth if sync repeatedly fails. */
+const OUTBOX_MAX_EVENTS_PER_SESSION = 500;
+const DEAD_LETTER_DIRNAME = "_dead-letter";
 async function ensureDir() {
     const dir = outboxDir();
     try {
@@ -46,6 +52,12 @@ async function ensureDir() {
         // Directory may already exist
     }
 }
+function deadLetterDir() {
+    return join(outboxDir(), DEAD_LETTER_DIRNAME);
+}
+function deadLetterPath(sessionId) {
+    return join(deadLetterDir(), `${normalizeSessionId(sessionId)}.jsonl`);
+}
 function outboxPath(sessionId) {
     return join(outboxDir(), `${normalizeSessionId(sessionId)}.json`);
 }
@@ -89,13 +101,79 @@ async function writeFileAtomic(targetPath, content, mode) {
     }
     await hardenPath(targetPath, mode);
 }
+async function appendOutboxDeadLetterRecord(sessionId, record) {
+    await ensureDir();
+    const dir = deadLetterDir();
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await hardenPath(dir, 0o700);
+    const targetPath = deadLetterPath(sessionId);
+    await appendFile(targetPath, `${JSON.stringify(record)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    await hardenPath(targetPath, 0o600);
+}
+export async function appendOutboxDeadLetter(sessionId, event, reason, error) {
+    const droppedAt = new Date().toISOString();
+    await appendOutboxDeadLetterRecord(sessionId, {
+        droppedAt,
+        queueId: normalizeSessionId(sessionId),
+        reason,
+        error: error ?? null,
+        event,
+    });
+}
+/** Drop stale events and enforce per-session cap. Returns true if any were removed. */
+function pruneOutboxEvents(events) {
+    const cutoff = Date.now() - OUTBOX_EVENT_TTL_MS;
+    const fresh = events.filter((e) => {
+        const epoch = Date.parse(e.timestamp);
+        return Number.isFinite(epoch) && epoch >= cutoff;
+    });
+    // Keep newest events if over cap.
+    const capped = fresh.length > OUTBOX_MAX_EVENTS_PER_SESSION
+        ? fresh.slice(fresh.length - OUTBOX_MAX_EVENTS_PER_SESSION)
+        : fresh;
+    return { pruned: capped, changed: capped.length !== events.length };
+}
 export async function readOutbox(sessionId) {
-    const targetPath = outboxPath(sessionId);
+    let targetPath;
+    try {
+        targetPath = outboxPath(sessionId);
+    }
+    catch {
+        return [];
+    }
     try {
         const raw = await readFile(targetPath, "utf8");
         try {
             const parsed = JSON.parse(raw);
-            return Array.isArray(parsed) ? parsed : [];
+            const events = Array.isArray(parsed) ? parsed : [];
+            const { pruned, changed } = pruneOutboxEvents(events);
+            const filtered = [];
+            let filteredChanged = changed;
+            for (const event of pruned) {
+                const skipReason = classifyOutboxReplaySkip(event);
+                if (!skipReason) {
+                    filtered.push(event);
+                    continue;
+                }
+                filteredChanged = true;
+                await appendOutboxDeadLetter(sessionId, event, `pruned_on_read:${skipReason}`, null);
+            }
+            // Write back if stale events were dropped.
+            if (filteredChanged) {
+                if (filtered.length === 0) {
+                    try {
+                        await unlink(targetPath);
+                    }
+                    catch { /* ok */ }
+                }
+                else {
+                    await writeFileAtomic(targetPath, JSON.stringify(filtered), 0o600);
+                }
+            }
+            return filtered;
         }
         catch {
             await backupCorruptOutboxFile(targetPath);
@@ -107,9 +185,21 @@ export async function readOutbox(sessionId) {
     }
 }
 export async function appendToOutbox(sessionId, event) {
+    let normalizedSessionId;
+    try {
+        normalizedSessionId = normalizeSessionId(sessionId);
+    }
+    catch {
+        return;
+    }
+    const skipReason = classifyOutboxReplaySkip(event);
+    if (skipReason) {
+        await appendOutboxDeadLetter(normalizedSessionId, event, `suppressed_on_append:${skipReason}`, null);
+        return;
+    }
     await ensureDir();
-    const targetPath = outboxPath(sessionId);
-    const existing = await readOutbox(sessionId);
+    const targetPath = outboxPath(normalizedSessionId);
+    const existing = await readOutbox(normalizedSessionId);
     const idx = existing.findIndex((item) => item.id === event.id);
     if (idx >= 0) {
         existing[idx] = event;
@@ -117,11 +207,18 @@ export async function appendToOutbox(sessionId, event) {
     else {
         existing.push(event);
     }
-    await writeFileAtomic(targetPath, JSON.stringify(existing, null, 2), 0o600);
+    await writeFileAtomic(targetPath, JSON.stringify(existing), 0o600);
 }
 export async function replaceOutbox(sessionId, events) {
+    let normalizedSessionId;
+    try {
+        normalizedSessionId = normalizeSessionId(sessionId);
+    }
+    catch {
+        return;
+    }
     await ensureDir();
-    const targetPath = outboxPath(sessionId);
+    const targetPath = outboxPath(normalizedSessionId);
     if (events.length === 0) {
         try {
             await unlink(targetPath);
@@ -132,7 +229,7 @@ export async function replaceOutbox(sessionId, events) {
             return;
         }
     }
-    await writeFileAtomic(targetPath, JSON.stringify(events, null, 2), 0o600);
+    await writeFileAtomic(targetPath, JSON.stringify(events), 0o600);
 }
 export async function readAllOutboxItems() {
     try {
@@ -209,8 +306,15 @@ export async function readOutboxSummary() {
     }
 }
 export async function clearOutbox(sessionId) {
+    let normalizedSessionId;
+    try {
+        normalizedSessionId = normalizeSessionId(sessionId);
+    }
+    catch {
+        return;
+    }
     try {
-        await unlink(outboxPath(sessionId));
+        await unlink(outboxPath(normalizedSessionId));
     }
     catch {
         // File may not exist

package/dist/paths.js

@@ -1,13 +1,32 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 function normalizeDirOverride(value) {
-    const trimmed = (value ?? "").trim();
+    let trimmed = (value ?? "").trim();
     if (!trimmed)
         return null;
-    if (trimmed.includes("\0"))
+    // `.env` values are often quoted; normalize them before validation.
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        trimmed = trimmed.slice(1, -1).trim();
+        if (!trimmed)
+            return null;
+    }
+    // Reject control characters to avoid malformed or ambiguous filesystem paths.
+    if (/[\u0000-\u001f\u007f]/.test(trimmed))
+        return null;
+    // Reject common escaped/encoded null-byte sequences as well.
+    if (/\\0|\\x00|\\u0000|%00/i.test(trimmed))
         return null;
     return trimmed;
 }
+function resolveOverridePath(override) {
+    if (override === "~")
+        return homedir();
+    if (override.startsWith("~/") || override.startsWith("~\\")) {
+        return resolve(homedir(), override.slice(2));
+    }
+    return resolve(override);
+}
 /**
  * Root directory for persistent OrgX plugin files.
  *
@@ -17,7 +36,7 @@ function normalizeDirOverride(value) {
 export function getOrgxPluginConfigDir() {
     const override = normalizeDirOverride(process.env.ORGX_OPENCLAW_PLUGIN_CONFIG_DIR);
     if (override)
-        return resolve(override);
+        return resolveOverridePath(override);
     return join(homedir(), ".config", "useorgx", "openclaw-plugin");
 }
 export function getOrgxPluginConfigPath(filename) {
@@ -32,7 +51,7 @@ export function getOrgxPluginConfigPath(filename) {
 export function getOpenClawDir() {
     const override = normalizeDirOverride(process.env.OPENCLAW_HOME);
     if (override)
-        return resolve(override);
+        return resolveOverridePath(override);
     return join(homedir(), ".openclaw");
 }
 /**
@@ -44,6 +63,6 @@ export function getOpenClawDir() {
 export function getOrgxOutboxDir() {
     const override = normalizeDirOverride(process.env.ORGX_OUTBOX_DIR);
     if (override)
-        return resolve(override);
+        return resolveOverridePath(override);
     return join(getOpenClawDir(), "orgx-outbox");
 }

package/dist/reporting/rollups.d.ts

@@ -18,3 +18,56 @@ export declare function computeWorkstreamRollup(taskStatuses?: unknown[]): TaskS
     status: WorkstreamRollupStatus;
     progressPct: number;
 };
+export type TaskCompletionReadiness = "ready" | "needs_proof" | "needs_review";
+export interface TaskCompletionReadinessResult {
+    ready: boolean;
+    status: TaskCompletionReadiness;
+    hasArtifact: boolean;
+    hasSchemaValidatedArtifact: boolean;
+    hasQualityScore: boolean;
+    qualityScore: number | null;
+    qualityThreshold: number;
+    missingItems: string[];
+    warnings: string[];
+}
+/**
+ * Evaluate whether a task has sufficient proof chain evidence to be marked
+ * complete. In phase 1 this is advisory (warn-only); callers decide whether
+ * to hard-block or soft-warn based on workspace config.
+ */
+export declare function computeTaskCompletionReadiness(input: {
+    artifacts?: Array<{
+        schema_validated?: boolean;
+        atomic_unit_type?: string;
+    }>;
+    qualityScore?: number | null;
+    qualityThreshold?: number;
+    hasOutcomeEvent?: boolean;
+}): TaskCompletionReadinessResult;
+export type LifecycleState = 'Queued' | 'Dispatching' | 'In Progress' | 'Blocked' | 'Completed' | 'Paused' | 'Failed';
+/**
+ * Derive an honest lifecycle state for an entity based on its raw status
+ * and child statuses. This is the authoritative backend derivation —
+ * the dashboard mirrors this logic in status-taxonomy.ts.
+ */
+export declare function deriveLifecycleState(rawStatus: unknown, childStatuses?: unknown[]): LifecycleState;
+/**
+ * Compute cascaded progress: parent progress derived from child task states.
+ * Returns a percentage (0–100) representing weighted completion.
+ */
+export declare function cascadeProgressFromChildren(childStatuses: unknown[]): number;
+export type EvalPassRateDriftResult = {
+    alert: boolean;
+    baselinePassRate: number;
+    rollingPassRate7d: number;
+    dropPct: number;
+    thresholdDropPct: number;
+    baselineSamples: number;
+    rollingSamples: number;
+};
+export declare function detectEvalPassRateDrift(input: {
+    passRates: unknown[];
+    thresholdDropPct?: number;
+    rollingWindowDays?: number;
+    baselineWindowDays?: number;
+}): EvalPassRateDriftResult | null;

package/dist/reporting/rollups.js

@@ -82,3 +82,151 @@ export function computeWorkstreamRollup(taskStatuses = []) {
         progressPct,
     };
 }
+function normalizePassRate(value) {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n))
+        return null;
+    if (n < 0)
+        return 0;
+    if (n <= 1)
+        return n;
+    if (n <= 100)
+        return n / 100;
+    return 1;
+}
+function average(values) {
+    if (values.length <= 0)
+        return 0;
+    const total = values.reduce((sum, value) => sum + value, 0);
+    return total / values.length;
+}
+/**
+ * Evaluate whether a task has sufficient proof chain evidence to be marked
+ * complete. In phase 1 this is advisory (warn-only); callers decide whether
+ * to hard-block or soft-warn based on workspace config.
+ */
+export function computeTaskCompletionReadiness(input) {
+    const artifacts = Array.isArray(input.artifacts) ? input.artifacts : [];
+    const qualityThreshold = typeof input.qualityThreshold === "number" && Number.isFinite(input.qualityThreshold)
+        ? input.qualityThreshold
+        : 4;
+    const qualityScore = typeof input.qualityScore === "number" && Number.isFinite(input.qualityScore)
+        ? input.qualityScore
+        : null;
+    const hasArtifact = artifacts.length > 0;
+    const hasSchemaValidatedArtifact = artifacts.some((a) => a.schema_validated === true && typeof a.atomic_unit_type === "string");
+    const hasQualityScore = qualityScore !== null;
+    const qualityMeetsThreshold = qualityScore !== null && qualityScore >= qualityThreshold;
+    const missingItems = [];
+    const warnings = [];
+    if (!hasArtifact) {
+        missingItems.push("No artifact registered for this task.");
+    }
+    else if (!hasSchemaValidatedArtifact) {
+        warnings.push("Artifact(s) present but none pass domain schema validation.");
+    }
+    if (!hasQualityScore) {
+        missingItems.push("No quality score recorded.");
+    }
+    else if (!qualityMeetsThreshold) {
+        missingItems.push(`Quality score ${qualityScore} below threshold ${qualityThreshold}.`);
+    }
+    if (input.hasOutcomeEvent === false) {
+        warnings.push("No outcome event recorded (L5 Impact not met).");
+    }
+    const ready = hasArtifact && hasQualityScore && qualityMeetsThreshold;
+    let status;
+    if (ready) {
+        status = "ready";
+    }
+    else if (hasArtifact && hasQualityScore) {
+        status = "needs_review";
+    }
+    else {
+        status = "needs_proof";
+    }
+    return {
+        ready,
+        status,
+        hasArtifact,
+        hasSchemaValidatedArtifact,
+        hasQualityScore,
+        qualityScore,
+        qualityThreshold,
+        missingItems,
+        warnings,
+    };
+}
+/**
+ * Derive an honest lifecycle state for an entity based on its raw status
+ * and child statuses. This is the authoritative backend derivation —
+ * the dashboard mirrors this logic in status-taxonomy.ts.
+ */
+export function deriveLifecycleState(rawStatus, childStatuses) {
+    const s = classifyTaskState(rawStatus);
+    if (s === 'done')
+        return 'Completed';
+    if (s === 'blocked')
+        return 'Blocked';
+    if (!childStatuses || childStatuses.length === 0) {
+        if (s === 'active')
+            return 'In Progress';
+        return 'Queued';
+    }
+    const counts = summarizeTaskStatuses(childStatuses);
+    if (counts.total > 0 && counts.done >= counts.total)
+        return 'Completed';
+    if (counts.blocked > 0 && counts.active === 0 && counts.done < counts.total)
+        return 'Blocked';
+    if (counts.active > 0 || counts.done > 0)
+        return 'In Progress';
+    return 'Queued';
+}
+/**
+ * Compute cascaded progress: parent progress derived from child task states.
+ * Returns a percentage (0–100) representing weighted completion.
+ */
+export function cascadeProgressFromChildren(childStatuses) {
+    if (!Array.isArray(childStatuses) || childStatuses.length === 0)
+        return 0;
+    const counts = summarizeTaskStatuses(childStatuses);
+    return toPercent(counts.done, counts.total);
+}
+export function detectEvalPassRateDrift(input) {
+    const thresholdDropPct = typeof input.thresholdDropPct === "number" && Number.isFinite(input.thresholdDropPct) && input.thresholdDropPct >= 0
+        ? input.thresholdDropPct
+        : 5;
+    const rollingWindowDays = typeof input.rollingWindowDays === "number" && Number.isFinite(input.rollingWindowDays) && input.rollingWindowDays > 0
+        ? Math.floor(input.rollingWindowDays)
+        : 7;
+    const baselineWindowDays = typeof input.baselineWindowDays === "number" &&
+        Number.isFinite(input.baselineWindowDays) &&
+        input.baselineWindowDays > 0
+        ? Math.floor(input.baselineWindowDays)
+        : rollingWindowDays;
+    const normalizedPassRates = (Array.isArray(input.passRates) ? input.passRates : [])
+        .map(normalizePassRate)
+        .filter((value) => value != null);
+    const requiredSamples = rollingWindowDays + baselineWindowDays;
+    if (normalizedPassRates.length < requiredSamples)
+        return null;
+    const rollingStart = normalizedPassRates.length - rollingWindowDays;
+    const baselineEnd = rollingStart;
+    const baselineStart = Math.max(0, baselineEnd - baselineWindowDays);
+    const rollingSlice = normalizedPassRates.slice(rollingStart);
+    const baselineSlice = normalizedPassRates.slice(baselineStart, baselineEnd);
+    if (rollingSlice.length <= 0 || baselineSlice.length <= 0)
+        return null;
+    const baselinePassRate = average(baselineSlice);
+    const rollingPassRate7d = average(rollingSlice);
+    const dropPct = Number(((baselinePassRate - rollingPassRate7d) * 100).toFixed(2));
+    return {
+        alert: dropPct > thresholdDropPct,
+        baselinePassRate: Number(baselinePassRate.toFixed(4)),
+        rollingPassRate7d: Number(rollingPassRate7d.toFixed(4)),
+        dropPct,
+        thresholdDropPct,
+        baselineSamples: baselineSlice.length,
+        rollingSamples: rollingSlice.length,
+    };
+}

package/dist/retro/domain-templates.d.ts

@@ -0,0 +1,45 @@
+type RetroFollowUp = {
+    title: string;
+    priority?: "p0" | "p1" | "p2";
+    reason?: string;
+};
+export type OrgxAgentRetroDomain = "engineering" | "product" | "design" | "marketing" | "sales" | "operations" | "orchestration" | "general";
+export declare function buildRetroTemplateForAgent(input: {
+    agentId: string | null | undefined;
+    success: boolean;
+    taskId: string | null | undefined;
+    runId: string;
+    errorMessage: string | null | undefined;
+}): {
+    domain: OrgxAgentRetroDomain;
+    summary: string;
+    whatWentWell: string[];
+    whatWentWrong: string[];
+    decisions: string[];
+    followUps: RetroFollowUp[];
+};
+/**
+ * Generate a structured retro using an LLM, falling back to the heuristic
+ * template produced by {@link buildRetroTemplateForAgent}.
+ *
+ * Caller: src/index.ts (~line 971) — `buildRetroTemplateForAgent` is invoked
+ * inside the session-stopped handler. Migrate that call site to use this
+ * function when ready to enable LLM-powered retros.
+ */
+export declare function buildRetroWithLlm(input: {
+    agentId: string | null | undefined;
+    success: boolean;
+    taskId: string | null | undefined;
+    runId: string;
+    errorMessage: string | null | undefined;
+    executionContext?: string | null;
+}): Promise<{
+    domain: OrgxAgentRetroDomain;
+    summary: string;
+    whatWentWell: string[];
+    whatWentWrong: string[];
+    decisions: string[];
+    followUps: RetroFollowUp[];
+    source: "llm" | "heuristic";
+}>;
+export {};