@agentic-workflow-kit/orchestrator 0.1.0

package/dist/runner/WorkflowRunner.js

@@ -0,0 +1,289 @@
+import path from 'node:path';
+import pLimit from 'p-limit';
+import { buildGenericPrompt } from '../drivers/codex-mcp/toolInput.js';
+import { safeName } from '../internal/guards.js';
+import { selectDispatchableStories } from '../scheduler/scheduler.js';
+import { CompletionGate } from './CompletionGate.js';
+import { MetricsCollector } from './MetricsCollector.js';
+import { RunJournal } from './RunJournal.js';
+const defaultChildTimer = {
+    setTimeout: (callback, ms) => globalThis.setTimeout(callback, ms),
+    clearTimeout: (handle) => globalThis.clearTimeout(handle),
+    setInterval: (callback, ms) => globalThis.setInterval(callback, ms),
+    clearInterval: (handle) => globalThis.clearInterval(handle),
+};
+export class WorkflowRunner {
+    dependencies;
+    state;
+    metrics;
+    journal;
+    completionGate;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+        this.metrics = new MetricsCollector(dependencies.clock);
+        this.journal = new RunJournal({ artifactStore: dependencies.artifactStore, clock: dependencies.clock });
+        this.completionGate = new CompletionGate({
+            gitInspector: dependencies.gitInspector,
+            statuses: dependencies.config.statuses,
+            git: dependencies.config.git,
+            childCwdAbs: dependencies.config.codex.childSession.cwdAbs,
+        });
+        this.state = {
+            runId: dependencies.runId,
+            command: dependencies.command,
+            workspaceRoot: dependencies.config.workspace.rootAbs,
+            artifactDir: path.join(dependencies.config.artifacts.runsDirAbs, dependencies.runId),
+            status: 'running',
+            maxParallel: dependencies.config.orchestrator.maxParallel,
+            startedAt: dependencies.clock.now(),
+            active: [],
+            completed: [],
+            blockedStoryId: null,
+            blockedReason: null,
+        };
+    }
+    async listEligible() {
+        const stories = await this.dependencies.storySource.listStories();
+        return stories.filter((story) => story.eligible);
+    }
+    async dryRunEligible() {
+        await this.journal.writeRunMetadata(this.state);
+        await this.journal.writeConfigSnapshot(this.dependencies.config);
+        await this.journal.record('run-started', { command: 'run-eligible', dryRun: true });
+        const stories = await this.dependencies.storySource.listStories();
+        await this.journal.writeStorySnapshot('initial', stories);
+        const dispatchable = selectDispatchableStories(stories, {
+            maxParallel: this.dependencies.config.orchestrator.maxParallel,
+        });
+        this.state = { ...this.state, status: 'dry-run', dryRunDispatch: dispatchable.map((story) => story.id) };
+        await this.writeState();
+        await this.writeLiveMetrics();
+        return { ...this.state };
+    }
+    async runStory(storyId, options = {}) {
+        await this.journal.writeRunMetadata(this.state);
+        await this.journal.writeConfigSnapshot(this.dependencies.config);
+        await this.journal.record('run-started', { command: 'run-story', storyId, force: options.force === true });
+        const stories = await this.dependencies.storySource.listStories();
+        await this.journal.writeStorySnapshot('initial', stories);
+        const story = stories.find((entry) => entry.id === storyId);
+        if (!story) {
+            this.blockOnce(storyId, `story ${storyId} was not found`);
+            return await this.finish();
+        }
+        if (!story.eligible && options.force !== true) {
+            this.blockOnce(story.id, story.blockedReason ?? `story ${story.id} is not eligible`);
+            return await this.finish();
+        }
+        const settled = await this.launchChild(story);
+        if (!settled.ok) {
+            await this.recordSettledChild(settled);
+            await this.journal.record('child-error', { storyId: settled.storyId, error: settled.error });
+            this.blockOnce(story.id, settled.error ?? 'child session failed');
+            return await this.finish();
+        }
+        const evaluation = await this.processSettled(settled);
+        if (!evaluation.complete) {
+            this.blockOnce(settled.storyId, evaluation.reason);
+            await this.journal.record('story-not-complete', {
+                storyId: settled.storyId,
+                status: evaluation.returnedStory?.status ?? null,
+            });
+            return await this.finish();
+        }
+        await this.journal.record('child-complete', { storyId: settled.storyId, sessionId: settled.sessionId });
+        return await this.finish();
+    }
+    async runEligible() {
+        await this.journal.writeRunMetadata(this.state);
+        await this.journal.writeConfigSnapshot(this.dependencies.config);
+        await this.journal.record('run-started', {
+            command: 'run-eligible',
+            maxParallel: this.dependencies.config.orchestrator.maxParallel,
+        });
+        let stories = await this.dependencies.storySource.listStories();
+        await this.journal.writeStorySnapshot('initial', stories);
+        const active = new Map();
+        const limit = pLimit(this.dependencies.config.orchestrator.maxParallel);
+        let stopLaunching = false;
+        const launchAvailable = async () => {
+            if (stopLaunching)
+                return;
+            const dispatchable = selectDispatchableStories(stories, {
+                maxParallel: this.dependencies.config.orchestrator.maxParallel,
+                activeIds: new Set(active.keys()),
+            });
+            const launched = [];
+            for (const story of dispatchable) {
+                await this.recordChildLaunch(story);
+                launched.push(story);
+            }
+            for (const story of launched) {
+                active.set(story.id, limit(() => this.executeChild(story)));
+            }
+        };
+        await launchAvailable();
+        if (active.size === 0)
+            return await this.finish();
+        while (active.size > 0) {
+            const settled = await Promise.race(active.values());
+            active.delete(settled.storyId);
+            if (!settled.ok) {
+                await this.recordSettledChild(settled);
+                await this.journal.record('child-error', { storyId: settled.storyId, error: settled.error });
+                this.blockOnce(settled.storyId, settled.error ?? 'child session failed');
+                stopLaunching = this.dependencies.config.orchestrator.stopLaunchingOnBlocked;
+                await this.writeState();
+                await this.writeLiveMetrics();
+                await launchAvailable();
+                continue;
+            }
+            stories = await this.dependencies.storySource.listStories();
+            const evaluation = await this.processSettled(settled, stories);
+            if (!evaluation.complete) {
+                this.blockOnce(settled.storyId, evaluation.reason);
+                await this.journal.record('story-not-complete', {
+                    storyId: settled.storyId,
+                    status: evaluation.returnedStory?.status ?? null,
+                });
+                stopLaunching = this.dependencies.config.orchestrator.stopLaunchingOnBlocked;
+                await launchAvailable();
+                continue;
+            }
+            await this.journal.record('child-complete', { storyId: settled.storyId, sessionId: settled.sessionId });
+            await launchAvailable();
+        }
+        return await this.finish();
+    }
+    async launchChild(story) {
+        await this.recordChildLaunch(story);
+        return await this.executeChild(story);
+    }
+    async recordChildLaunch(story) {
+        this.metrics.start(story.id);
+        this.state = { ...this.state, active: [...this.state.active, story.id] };
+        await this.journal.record('child-launched', { storyId: story.id });
+        await this.writeState();
+        await this.writeLiveMetrics();
+    }
+    async executeChild(story) {
+        const timeoutMs = this.dependencies.config.orchestrator.childTimeoutMs;
+        const timer = this.dependencies.childTimer ?? defaultChildTimer;
+        const startedAtMs = this.dependencies.clock.nowMs();
+        const childCwd = this.dependencies.config.codex.childSession.cwdAbs;
+        const baseShaAtLaunch = (await this.dependencies.gitInspector.snapshotBaseSha?.({
+            git: this.dependencies.config.git,
+            cwdAbs: childCwd,
+        })) ?? null;
+        let timeoutHandle;
+        let heartbeatHandle;
+        try {
+            const run = this.dependencies.storyRunner.runStory({
+                story,
+                prompt: buildGenericPrompt(story, this.dependencies.config.git),
+                cwd: childCwd,
+                metadata: { runId: this.state.runId },
+            });
+            const timeout = new Promise((_, reject) => {
+                timeoutHandle = timer.setTimeout(() => reject(new Error('child-timeout')), timeoutMs);
+            });
+            heartbeatHandle = timer.setInterval(() => {
+                void this.journal.record('child-heartbeat', {
+                    storyId: story.id,
+                    elapsedMs: this.dependencies.clock.nowMs() - startedAtMs,
+                });
+            }, heartbeatIntervalMs(timeoutMs));
+            const result = await Promise.race([run, timeout]);
+            const completedAt = this.metrics.complete(story.id);
+            this.state = { ...this.state, active: this.state.active.filter((entry) => entry !== story.id) };
+            if (result.metrics) {
+                this.metrics.updateChildMetric(story.id, result.metrics);
+                await this.dependencies.artifactStore.writeJson(`children/${safeName(story.id)}.metrics.json`, result.metrics);
+            }
+            return {
+                storyId: story.id,
+                ok: true,
+                sessionId: result.sessionId,
+                content: result.content,
+                rawResult: result.rawResult,
+                invocation: result.invocation,
+                completedAt,
+                metrics: result.metrics,
+                baseShaAtLaunch,
+            };
+        }
+        catch (error) {
+            const completedAt = this.metrics.complete(story.id);
+            this.state = { ...this.state, active: this.state.active.filter((entry) => entry !== story.id) };
+            return {
+                storyId: story.id,
+                ok: false,
+                sessionId: null,
+                error: error instanceof Error ? error.message : String(error),
+                completedAt,
+                baseShaAtLaunch,
+            };
+        }
+        finally {
+            if (timeoutHandle !== undefined)
+                timer.clearTimeout(timeoutHandle);
+            if (heartbeatHandle !== undefined)
+                timer.clearInterval(heartbeatHandle);
+        }
+    }
+    async processSettled(settled, stories) {
+        const returnedStories = stories ?? (await this.dependencies.storySource.listStories());
+        await this.journal.writeStorySnapshot(`after-${settled.storyId}`, returnedStories);
+        const evaluation = await this.completionGate.evaluate(settled, returnedStories);
+        const settledWithEvidence = evaluation.commitEvidence
+            ? { ...settled, commitEvidence: evaluation.commitEvidence }
+            : settled;
+        await this.recordSettledChild(settledWithEvidence, evaluation.returnedStory, evaluation.complete);
+        return evaluation;
+    }
+    async recordSettledChild(settled, returnedStory, returnedComplete) {
+        const entry = await this.journal.recordSettledChild(this.metrics, settled, returnedStory, returnedComplete);
+        this.state = { ...this.state, completed: [...this.state.completed, entry] };
+        await this.writeState();
+        await this.writeLiveMetrics();
+    }
+    blockOnce(storyId, reason) {
+        if (this.state.status === 'blocked')
+            return;
+        this.state = { ...this.state, status: 'blocked', blockedStoryId: storyId, blockedReason: reason };
+        this.dependencies.logger.warn('run blocked', { storyId, reason });
+    }
+    async finish() {
+        if (this.state.status !== 'blocked' && this.state.status !== 'dry-run') {
+            this.state = { ...this.state, status: 'complete' };
+            await this.journal.record('run-complete');
+        }
+        else if (this.state.status === 'blocked') {
+            await this.journal.record('run-blocked', {
+                blockedStoryId: this.state.blockedStoryId,
+                blockedReason: this.state.blockedReason,
+            });
+        }
+        const completedAt = this.dependencies.clock.now();
+        const runMetrics = this.metrics.buildRunMetrics({
+            startedAt: this.state.startedAt,
+            completedAt,
+            completedCount: this.state.completed.length,
+            status: this.state.status,
+            blockedReason: this.state.blockedReason,
+        });
+        this.state = { ...this.state, completedAt, metrics: runMetrics };
+        await this.writeState();
+        await this.writeLiveMetrics();
+        return { ...this.state };
+    }
+    async writeState() {
+        await this.journal.writeState(this.state);
+    }
+    async writeLiveMetrics() {
+        await this.journal.writeLiveMetrics(this.state, this.metrics.observedChildMetrics());
+    }
+}
+function heartbeatIntervalMs(timeoutMs) {
+    return Math.max(1, Math.floor(timeoutMs / 4));
+}

package/dist/scheduler/scheduler.d.ts

@@ -0,0 +1,8 @@
+import type { WorkflowStory } from '../types.js';
+export interface SelectStoriesOptions {
+    maxParallel: number;
+    activeIds?: Set<string>;
+}
+export declare function selectDispatchableStories(stories: WorkflowStory[], options: SelectStoriesOptions): WorkflowStory[];
+export declare function isCompleteStatus(status: string | undefined, completeStatuses: string[]): boolean;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/scheduler/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,OAAO,EAAE,oBAAoB,GAAG,aAAa,EAAE,CAIlH;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,OAAO,CAEhG"}

package/dist/scheduler/scheduler.js

@@ -0,0 +1,8 @@
+export function selectDispatchableStories(stories, options) {
+    const activeIds = options.activeIds ?? new Set();
+    const slots = Math.max(0, options.maxParallel - activeIds.size);
+    return stories.filter((story) => story.eligible && !activeIds.has(story.id)).slice(0, slots);
+}
+export function isCompleteStatus(status, completeStatuses) {
+    return status !== undefined && completeStatuses.includes(status);
+}

package/dist/tracks/markdownTracker.d.ts

@@ -0,0 +1,29 @@
+import type { StorySource, WorkflowStory, WorkflowTrack } from '../types.js';
+export interface DiscoverMarkdownTracksOptions {
+    workspaceRoot: string;
+    tracksDir: string;
+    archiveDir: string;
+    completeStatuses: string[];
+    eligibleStatuses: string[];
+    idPattern: string;
+}
+export interface ParseTrackerStoriesContext {
+    completeStatuses: Set<string>;
+    eligibleStatuses: Set<string>;
+    idPattern: RegExp;
+    trackId: string;
+    trackTitle: string;
+    trackerPath: string;
+}
+export declare class MarkdownTrackStorySource implements StorySource {
+    private readonly options;
+    private readonly trackId;
+    constructor(options: DiscoverMarkdownTracksOptions, trackId: string);
+    listStories(): Promise<WorkflowStory[]>;
+}
+export declare class EmptyStorySource implements StorySource {
+    listStories(): Promise<WorkflowStory[]>;
+}
+export declare function discoverMarkdownTracks(options: DiscoverMarkdownTracksOptions): Promise<WorkflowTrack[]>;
+export declare function parseTrackerStories(markdown: string, context: ParseTrackerStoriesContext): WorkflowStory[];
+//# sourceMappingURL=markdownTracker.d.ts.map

package/dist/tracks/markdownTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownTracker.d.ts","sourceRoot":"","sources":["../../src/tracks/markdownTracker.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAK7E,MAAM,WAAW,6BAA6B;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,wBAAyB,YAAW,WAAW;IAExD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,OAAO,EAAE,6BAA6B,EACtC,OAAO,EAAE,MAAM;IAG5B,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;CAM9C;AAED,qBAAa,gBAAiB,YAAW,WAAW;IAC5C,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;CAG9C;AAED,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CA2C7G;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,GAAG,aAAa,EAAE,CA4B1G"}