@minionry/minion 0.7.36 → 0.7.39

package/dist/server/services/chain/chain-engine.js

@@ -0,0 +1,494 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+import { getClientId } from '../client-id.js';
+import { resolveActiveBoardId } from '../plan/board-config.js';
+import { isBoardPlanning } from '../plan/composer.js';
+import { parseBoardDirectory, resolvePmDir } from '../plan/parser.js';
+import { writeRunInputFile } from '../schedule/run-bootstrap.js';
+import { logAppAudit } from '../sdk/audit.js';
+import { getGrant } from '../sdk/grant-store.js';
+import { makeSpaceKey } from '../settings.js';
+import { broadcastBoardRunPrompt } from '../websocket/plan-execution-handlers.js';
+import { chainEngineCache, executorCache, schedulerCache } from '../websocket/plan-helpers.js';
+import { startFreshBoardRun } from '../websocket/sdk-pm-execution-host.js';
+import { ChainStore, MAX_CHAIN_DEPTH, } from './chain-store.js';
+export const CHAIN_START_MAX_ATTEMPTS = 3;
+export const CHAIN_START_BACKOFF_MS = 30_000;
+export const CHAIN_DRAIN_TICK_MS = 30_000;
+export const CHAIN_START_GRACE_MS = 15_000;
+export const CHAIN_ERRORS = {
+    missing: 'target board no longer exists',
+    notRunnable: 'target board is not runnable',
+    paused: 'target board is paused',
+    noIssues: 'target board has no issues',
+    startFailed: 'the downstream run could not be started',
+};
+function nonEpicIssues(board) {
+    return board.issues.filter((i) => i.type !== 'epic');
+}
+export function classifySettle(board, signal) {
+    if (!board)
+        return null;
+    const issues = nonEpicIssues(board);
+    if (issues.length === 0)
+        return null;
+    if (board.state.paused)
+        return null;
+    if (issues.some((i) => i.status === 'awaiting_approval'))
+        return null;
+    if (issues.every((i) => i.status === 'done'))
+        return 'success';
+    if (issues.every((i) => i.status === 'done' || i.status === 'cancelled'))
+        return 'failure';
+    return signal === 'error' ? 'failure' : null;
+}
+export function computeSettleKey(outcome, boardId, issues) {
+    const lines = issues.map((i) => `${i.id}=${i.status}`).sort();
+    const digest = createHash('sha256').update(`${boardId}\n${lines.join('\n')}`).digest('hex');
+    return `${outcome}:${digest.slice(0, 16)}`;
+}
+export function conditionMatches(on, outcome) {
+    return on === 'settled' || on === outcome;
+}
+const UPSTREAM_MAX_FILE_BYTES = 256 * 1024;
+const UPSTREAM_MAX_TOTAL_BYTES = 2 * 1024 * 1024;
+const UPSTREAM_MAX_ENTRIES = 50;
+function classifyUpstreamEntry(outDir, realOutDir, boardId, name, acceptedCount, totalBytes) {
+    let real;
+    try {
+        real = realpathSync(join(outDir, name));
+    }
+    catch {
+        return { kind: 'silent' };
+    }
+    const rel = relative(realOutDir, real);
+    if (rel.startsWith('..') || isAbsolute(rel))
+        return { kind: 'silent' };
+    let stat;
+    try {
+        stat = statSync(real);
+    }
+    catch {
+        return { kind: 'silent' };
+    }
+    if (!stat.isFile())
+        return { kind: 'omitted', entry: { name, reason: 'not_a_regular_file' } };
+    if (acceptedCount >= UPSTREAM_MAX_ENTRIES)
+        return { kind: 'omitted', entry: { name, reason: 'over_count' } };
+    if (stat.size > UPSTREAM_MAX_FILE_BYTES)
+        return { kind: 'omitted', entry: { name, reason: 'too_large' } };
+    if (totalBytes + stat.size > UPSTREAM_MAX_TOTAL_BYTES)
+        return { kind: 'omitted', entry: { name, reason: 'over_total' } };
+    return { kind: 'output', entry: { name, path: `boards/${boardId}/out/${name}`, bytes: stat.size } };
+}
+function buildUpstreamOutputs(pmDir, boardId) {
+    const outDir = join(pmDir, 'boards', boardId, 'out');
+    const outputs = [];
+    const omitted = [];
+    if (!existsSync(outDir))
+        return { outputs, omitted };
+    let realOutDir;
+    let names;
+    try {
+        realOutDir = realpathSync(outDir);
+        names = readdirSync(outDir);
+    }
+    catch {
+        return { outputs, omitted };
+    }
+    let totalBytes = 0;
+    for (const name of names.filter((n) => n.endsWith('.md')).sort()) {
+        const verdict = classifyUpstreamEntry(outDir, realOutDir, boardId, name, outputs.length, totalBytes);
+        if (verdict.kind === 'silent')
+            continue;
+        if (verdict.kind === 'omitted') {
+            omitted.push(verdict.entry);
+            continue;
+        }
+        totalBytes += verdict.entry.bytes;
+        outputs.push(verdict.entry);
+    }
+    return { outputs, omitted };
+}
+export function buildChainLinkWires(store) {
+    return store.list().map((link) => ({ ...link, history: store.getFireHistory(link.id) }));
+}
+export function broadcastChainsChanged(ctx, store) {
+    ctx.broadcastToAll({ type: 'planChainsChanged', data: { links: buildChainLinkWires(store) } });
+}
+export function broadcastChainFired(ctx, fire) {
+    ctx.broadcastToAll({
+        type: 'planChainFired',
+        data: {
+            linkId: fire.linkId,
+            fireId: fire.id,
+            from: fire.from,
+            to: fire.to,
+            status: fire.status,
+            upstreamOutcome: fire.upstreamOutcome,
+            ...(fire.skipReason ? { skipReason: fire.skipReason } : {}),
+            ...(fire.error ? { error: fire.error } : {}),
+            ...(fire.downstreamRunId ? { downstreamRunId: fire.downstreamRunId } : {}),
+            lineage: fire.lineage,
+            at: fire.claimedAt,
+            ...(fire.completedAt ? { completedAt: fire.completedAt } : {}),
+        },
+    });
+}
+export class ChainEngine {
+    workingDir;
+    ctx;
+    deps;
+    drainTickMs;
+    startGraceMs;
+    timer = null;
+    graceTimer = null;
+    store = null;
+    drainNotBefore = 0;
+    needsReload = false;
+    draining = false;
+    constructor(workingDir, ctx, deps = {}) {
+        this.workingDir = workingDir;
+        this.ctx = ctx;
+        this.deps = deps;
+        this.drainTickMs = deps.drainTickMs ?? CHAIN_DRAIN_TICK_MS;
+        this.startGraceMs = deps.startGraceMs ?? CHAIN_START_GRACE_MS;
+    }
+    getStore() {
+        return this.store;
+    }
+    isRunning() {
+        return this.timer !== null;
+    }
+    start() {
+        if (this.timer)
+            return;
+        if (!resolvePmDir(this.workingDir))
+            return;
+        this.store = new ChainStore(this.workingDir);
+        this.drainNotBefore = this.nowMs() + this.startGraceMs;
+        this.needsReload = true;
+        this.graceTimer = setTimeout(() => this.drain(), this.startGraceMs);
+        if (typeof this.graceTimer.unref === 'function')
+            this.graceTimer.unref();
+        this.timer = setInterval(() => this.drain(), this.drainTickMs);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (this.graceTimer) {
+            clearTimeout(this.graceTimer);
+            this.graceTimer = null;
+        }
+        this.store = null;
+    }
+    notifyRunEnded(boardId, signal) {
+        try {
+            const pmDir = resolvePmDir(this.workingDir);
+            if (!pmDir)
+                return;
+            const settledBoardId = boardId ?? resolveActiveBoardId(pmDir);
+            if (!settledBoardId)
+                return;
+            if (!this.store)
+                this.start();
+            const store = this.store;
+            if (!store)
+                return;
+            const board = parseBoardDirectory(pmDir, settledBoardId);
+            const outcome = classifySettle(board, signal);
+            if (!outcome || !board)
+                return;
+            this.answerSettle(store, settledBoardId, board, outcome);
+        }
+        catch (error) {
+            console.error('[ChainEngine] notifyRunEnded failed:', error);
+        }
+        finally {
+            this.scheduleDrain();
+        }
+    }
+    answerSettle(store, boardId, board, outcome) {
+        const settleKey = computeSettleKey(outcome, boardId, nonEpicIssues(board));
+        const source = store.findLineageSource(boardId);
+        const upstreamLineage = source?.lineage.length ? source.lineage : [boardId];
+        const candidates = store.list().filter((l) => l.from === boardId && l.enabled && l.state === 'armed');
+        let wrote = false;
+        for (const link of candidates) {
+            const record = this.answerSettleForLink(store, link, settleKey, outcome, upstreamLineage);
+            if (!record)
+                continue;
+            wrote = true;
+            broadcastChainFired(this.ctx, record);
+            this.auditFire(link, record);
+        }
+        if (source)
+            store.markLineageConsumed(source.id);
+        if (wrote)
+            broadcastChainsChanged(this.ctx, store);
+    }
+    answerSettleForLink(store, link, settleKey, outcome, upstreamLineage) {
+        const context = { upstreamOutcome: outcome, lineage: [...upstreamLineage, link.to] };
+        if (!conditionMatches(link.on, outcome)) {
+            return store.recordSkip(link.id, settleKey, 'condition_not_met', context);
+        }
+        const guard = lineageRefusal(link.to, upstreamLineage);
+        if (guard)
+            return store.recordSkip(link.id, settleKey, guard, context);
+        return store.claimFire(link.id, settleKey, context);
+    }
+    notifyExecutorStatus(status) {
+        if (status === 'starting' || status === 'executing')
+            return;
+        this.scheduleDrain();
+    }
+    scheduleDrain() {
+        const deferred = setTimeout(() => this.drain(), 0);
+        if (typeof deferred.unref === 'function')
+            deferred.unref();
+    }
+    drain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        try {
+            this.drainOnce();
+        }
+        catch (error) {
+            console.error('[ChainEngine] drain failed:', error);
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    drainOnce() {
+        const store = this.store;
+        if (!store)
+            return;
+        const now = this.nowMs();
+        if (now < this.drainNotBefore)
+            return;
+        if (this.needsReload) {
+            store.reload();
+            this.needsReload = false;
+        }
+        if (this.isSpaceBusy())
+            return;
+        for (const pending of store.listPendingFires()) {
+            const fire = store.getFire(pending.id);
+            if (!fire || fire.status !== 'pending')
+                continue;
+            if (fire.nextAttemptAt && Date.parse(fire.nextAttemptAt) > now)
+                continue;
+            if (this.isTargetHeld(fire.to))
+                continue;
+            if (this.attemptFire(store, fire))
+                return;
+        }
+    }
+    attemptFire(store, fire) {
+        const link = store.get(fire.linkId);
+        if (!link)
+            return this.terminate(store, fire, { status: 'skipped', skipReason: 'link_deleted' });
+        if (!link.enabled || link.state !== 'armed') {
+            return this.terminate(store, fire, { status: 'skipped', skipReason: 'link_disabled' });
+        }
+        if (!this.hasGrant(link.createdBy)) {
+            return this.terminate(store, fire, { status: 'skipped', skipReason: 'grant_revoked' });
+        }
+        const guard = lineageRefusal(fire.to, fire.lineage.slice(0, -1));
+        if (guard)
+            return this.terminate(store, fire, { status: 'skipped', skipReason: guard });
+        if (store.isOnArmedCycle(fire.linkId)) {
+            return this.terminate(store, fire, { status: 'skipped', skipReason: 'cycle' });
+        }
+        const precheck = this.precheckTarget(fire.to);
+        if (precheck)
+            return this.terminate(store, fire, { status: 'failed', error: precheck });
+        if (link.passOutputs)
+            this.writeUpstreamManifest(link, fire);
+        const launchPrompt = `Chain ${link.id}: run board ${fire.to} — board ${fire.from} settled (${fire.upstreamOutcome})`;
+        let runId;
+        try {
+            const start = this.deps.startRun ?? startFreshBoardRun;
+            runId = start(this.ctx, this.workingDir, fire.to, { launchPrompt }).runId;
+        }
+        catch (error) {
+            console.error(`[ChainEngine] start of board ${fire.to} threw:`, error);
+            this.recordTransientFailure(store, fire);
+            return true;
+        }
+        const started = store.completeFire(fire.id, { status: 'started', downstreamRunId: runId });
+        if (started) {
+            broadcastChainFired(this.ctx, started);
+            this.auditFire(link, started);
+        }
+        broadcastChainsChanged(this.ctx, store);
+        return true;
+    }
+    terminate(store, fire, outcome) {
+        const record = store.completeFire(fire.id, outcome);
+        if (!record)
+            return false;
+        broadcastChainFired(this.ctx, record);
+        this.auditFire(store.get(record.linkId), record);
+        broadcastChainsChanged(this.ctx, store);
+        return false;
+    }
+    recordTransientFailure(store, fire) {
+        const attempts = fire.attempts + 1;
+        if (attempts >= CHAIN_START_MAX_ATTEMPTS) {
+            this.terminate(store, fire, { status: 'failed', error: CHAIN_ERRORS.startFailed });
+            return;
+        }
+        const backoff = CHAIN_START_BACKOFF_MS * 2 ** (attempts - 1);
+        const updated = store.recordStartAttempt(fire.id, new Date(this.nowMs() + backoff).toISOString());
+        if (!updated)
+            return;
+        broadcastChainFired(this.ctx, updated);
+        broadcastChainsChanged(this.ctx, store);
+    }
+    isSpaceBusy() {
+        if (this.deps.spaceBusy)
+            return this.deps.spaceBusy(this.workingDir);
+        const executor = executorCache.get(this.workingDir);
+        if (!executor)
+            return false;
+        return executor.isRunning() || executor.getStatus() === 'paused';
+    }
+    isTargetHeld(boardId) {
+        if (this.deps.targetHeld)
+            return this.deps.targetHeld(this.workingDir, boardId);
+        if (isBoardPlanning(this.workingDir, boardId))
+            return true;
+        const scheduler = schedulerCache.get(this.workingDir);
+        return scheduler?.runs.snapshotValues().some((run) => run.boardId === boardId) ?? false;
+    }
+    hasGrant(createdBy) {
+        if (this.deps.hasChainGrant)
+            return this.deps.hasChainGrant(createdBy, this.workingDir);
+        try {
+            const spaceKey = makeSpaceKey(getClientId(), this.workingDir);
+            return getGrant(createdBy, spaceKey)?.scopes.includes('pm:chain') === true;
+        }
+        catch (error) {
+            console.error('[ChainEngine] grant re-check failed:', error);
+            return false;
+        }
+    }
+    precheckTarget(boardId) {
+        const pmDir = resolvePmDir(this.workingDir);
+        if (!pmDir)
+            return CHAIN_ERRORS.missing;
+        const boardsDir = join(pmDir, 'boards');
+        let entries = [];
+        try {
+            entries = existsSync(boardsDir) ? readdirSync(boardsDir) : [];
+        }
+        catch {
+            entries = [];
+        }
+        if (!entries.includes(boardId))
+            return CHAIN_ERRORS.missing;
+        const board = parseBoardDirectory(pmDir, boardId);
+        if (!board)
+            return CHAIN_ERRORS.missing;
+        if (board.board.status === 'completed' || board.board.status === 'archived')
+            return CHAIN_ERRORS.notRunnable;
+        if (board.state.paused)
+            return CHAIN_ERRORS.paused;
+        if (nonEpicIssues(board).length === 0 && !isBoardPlanning(this.workingDir, boardId)) {
+            return CHAIN_ERRORS.noIssues;
+        }
+        return null;
+    }
+    writeUpstreamManifest(link, fire) {
+        const pmDir = resolvePmDir(this.workingDir);
+        if (!pmDir)
+            return;
+        const upstream = {
+            linkId: link.id,
+            boardId: fire.from,
+            outcome: fire.upstreamOutcome,
+            settledAt: fire.claimedAt,
+            lineage: fire.lineage,
+            ...buildUpstreamOutputs(pmDir, fire.from),
+        };
+        try {
+            const written = writeRunInputFile(join(pmDir, 'boards', fire.to), { boardId: fire.to, upstream });
+            if (written === null) {
+                broadcastBoardRunPrompt(this.ctx, fire.to, `Chain ${link.id}: board ${fire.to}'s existing run-input.json could not be parsed — starting without the upstream-outputs manifest.`);
+            }
+        }
+        catch (error) {
+            console.error(`[ChainEngine] failed to write upstream run-input for board ${fire.to}:`, error);
+        }
+    }
+    auditFire(link, fire) {
+        if (!link)
+            return;
+        if (fire.status === 'pending')
+            return;
+        if (fire.status === 'skipped' && fire.skipReason === 'condition_not_met')
+            return;
+        const method = fire.status === 'started'
+            ? 'pm.chains.fire.started'
+            : fire.status === 'skipped'
+                ? 'pm.chains.fire.skipped'
+                : 'pm.chains.fire.failed';
+        const reason = fire.status === 'started'
+            ? `link ${link.id} started board ${fire.to} (run ${fire.downstreamRunId}) after ${fire.from} settled ${fire.upstreamOutcome}`
+            : fire.status === 'skipped'
+                ? `link ${link.id} skipped: ${fire.skipReason}`
+                : `link ${link.id} failed: ${fire.error}`;
+        try {
+            logAppAudit({
+                appId: link.createdBy,
+                origin: link.createdByOrigin ?? '',
+                method,
+                decision: fire.status === 'started' ? 'allow' : 'deny',
+                requestId: `chain:${fire.id}`,
+                spaceKey: makeSpaceKey(getClientId(), this.workingDir),
+                reason,
+            });
+        }
+        catch (error) {
+            console.error('[ChainEngine] audit failed:', error);
+        }
+    }
+    nowMs() {
+        return this.deps.now ? this.deps.now() : Date.now();
+    }
+}
+function lineageRefusal(to, upstreamLineage) {
+    if (upstreamLineage.includes(to))
+        return 'cycle';
+    if (upstreamLineage.length + 1 > MAX_CHAIN_DEPTH)
+        return 'max_depth';
+    return null;
+}
+export function getChainEngine(workingDir, ctx, deps) {
+    let engine = chainEngineCache.get(workingDir);
+    if (!engine) {
+        engine = new ChainEngine(workingDir, ctx, deps);
+        chainEngineCache.set(workingDir, engine);
+    }
+    return engine;
+}
+export function stopAllChainEngines() {
+    for (const engine of chainEngineCache.values()) {
+        try {
+            engine.stop();
+        }
+        catch {
+        }
+    }
+    chainEngineCache.clear();
+}