@workflow-manager/runner 0.1.0 → 0.3.0

package/dist/runnerApi.js

@@ -0,0 +1,221 @@
+import http from "node:http";
+function jsonResponse(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json");
+    res.setHeader("Content-Length", Buffer.byteLength(payload));
+    res.end(payload);
+}
+function errorResponse(res, status, error, message) {
+    jsonResponse(res, status, { error, message });
+}
+function isAuthorized(req, store) {
+    const header = req.headers.authorization;
+    return header === `Bearer ${store.attachToken()}`;
+}
+function parseBoolean(value, fallback) {
+    if (value === null) {
+        return fallback;
+    }
+    return value !== "false";
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    if (chunks.length === 0) {
+        return {};
+    }
+    const raw = Buffer.concat(chunks).toString("utf-8").trim();
+    if (!raw) {
+        return {};
+    }
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Request body must be a JSON object");
+    }
+    return parsed;
+}
+export async function startRunnerApiServer(store, requestedPort) {
+    const sockets = new Set();
+    const server = http.createServer((req, res) => {
+        void (async () => {
+            const method = req.method ?? "GET";
+            const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "127.0.0.1"}`);
+            const pathname = url.pathname;
+            if (method === "GET" && pathname === "/health") {
+                jsonResponse(res, 200, { ok: true });
+                return;
+            }
+            if (!isAuthorized(req, store)) {
+                errorResponse(res, 401, "unauthorized", "Missing or invalid attach token");
+                return;
+            }
+            if (method === "GET" && pathname === "/session") {
+                jsonResponse(res, 200, store.publicSession());
+                return;
+            }
+            const runMatch = pathname.match(/^\/runs\/([^/]+)$/);
+            if (method === "GET" && runMatch) {
+                const runId = decodeURIComponent(runMatch[1] ?? "");
+                if (!store.isKnownRun(runId)) {
+                    errorResponse(res, 404, "not_found", `Unknown run: ${runId}`);
+                    return;
+                }
+                jsonResponse(res, 200, store.snapshot());
+                return;
+            }
+            const stepMatch = pathname.match(/^\/runs\/([^/]+)\/steps\/([^/]+)$/);
+            if (method === "GET" && stepMatch) {
+                const runId = decodeURIComponent(stepMatch[1] ?? "");
+                const stepKey = decodeURIComponent(stepMatch[2] ?? "");
+                if (!store.isKnownRun(runId)) {
+                    errorResponse(res, 404, "not_found", `Unknown run: ${runId}`);
+                    return;
+                }
+                const step = store.stepDetail(stepKey);
+                if (!step) {
+                    errorResponse(res, 404, "not_found", `Unknown step: ${stepKey}`);
+                    return;
+                }
+                jsonResponse(res, 200, step);
+                return;
+            }
+            const logsMatch = pathname.match(/^\/runs\/([^/]+)\/logs$/);
+            if (method === "GET" && logsMatch) {
+                const runId = decodeURIComponent(logsMatch[1] ?? "");
+                if (!store.isKnownRun(runId)) {
+                    errorResponse(res, 404, "not_found", `Unknown run: ${runId}`);
+                    return;
+                }
+                const stepKey = url.searchParams.get("stepKey") ?? undefined;
+                const limit = Number.parseInt(url.searchParams.get("limit") ?? "200", 10);
+                const cursor = url.searchParams.get("cursor") ?? undefined;
+                jsonResponse(res, 200, store.listLogs(stepKey, limit, cursor));
+                return;
+            }
+            const controlMatch = pathname.match(/^\/runs\/([^/]+)\/(approve|resume|cancel)$/);
+            if (method === "POST" && controlMatch) {
+                const runId = decodeURIComponent(controlMatch[1] ?? "");
+                const action = controlMatch[2] ?? "";
+                if (!store.isKnownRun(runId)) {
+                    errorResponse(res, 404, "not_found", `Unknown run: ${runId}`);
+                    return;
+                }
+                let body;
+                try {
+                    body = await readJsonBody(req);
+                }
+                catch (error) {
+                    errorResponse(res, 400, "invalid_body", error.message);
+                    return;
+                }
+                const stepKey = typeof body.stepKey === "string" ? body.stepKey : undefined;
+                const metadata = {
+                    actor: typeof body.actor === "string" ? body.actor : undefined,
+                    note: typeof body.note === "string" ? body.note : undefined,
+                    source: typeof body.source === "string" ? body.source : "api",
+                };
+                const result = action === "cancel"
+                    ? store.cancel(stepKey, metadata)
+                    : action === "resume"
+                        ? store.resume(stepKey, metadata)
+                        : store.approve(stepKey, metadata);
+                if (!result.ok) {
+                    errorResponse(res, 409, "conflict", result.reason ?? "Unable to update run state");
+                    return;
+                }
+                jsonResponse(res, 200, {
+                    ok: true,
+                    decision: action === "cancel" ? "cancelled" : "approved",
+                    stepKey: result.stepKey ?? stepKey ?? null,
+                    actor: metadata.actor ?? null,
+                    note: metadata.note ?? null,
+                    source: metadata.source,
+                });
+                return;
+            }
+            const eventsMatch = pathname.match(/^\/runs\/([^/]+)\/events$/);
+            if (method === "GET" && eventsMatch) {
+                const runId = decodeURIComponent(eventsMatch[1] ?? "");
+                if (!store.isKnownRun(runId)) {
+                    errorResponse(res, 404, "not_found", `Unknown run: ${runId}`);
+                    return;
+                }
+                const sinceSequence = Number.parseInt(url.searchParams.get("sinceSequence") ?? "0", 10) || undefined;
+                const includeLogs = parseBoolean(url.searchParams.get("includeLogs"), true);
+                res.statusCode = 200;
+                res.setHeader("Content-Type", "text/event-stream");
+                res.setHeader("Cache-Control", "no-cache");
+                res.setHeader("Connection", "keep-alive");
+                res.flushHeaders?.();
+                for (const event of store.events(sinceSequence, includeLogs)) {
+                    res.write(`event: ${event.type}\n`);
+                    res.write(`id: ${event.sequence}\n`);
+                    res.write(`data: ${JSON.stringify(event)}\n\n`);
+                }
+                const heartbeat = setInterval(() => {
+                    res.write("event: heartbeat\n");
+                    res.write(`data: ${JSON.stringify({ occurredAt: new Date().toISOString() })}\n\n`);
+                }, 15000);
+                const unsubscribe = store.subscribe((event) => {
+                    if (!includeLogs && (event.type === "agent.stdout" || event.type === "agent.stderr")) {
+                        return;
+                    }
+                    res.write(`event: ${event.type}\n`);
+                    res.write(`id: ${event.sequence}\n`);
+                    res.write(`data: ${JSON.stringify(event)}\n\n`);
+                });
+                const cleanup = () => {
+                    clearInterval(heartbeat);
+                    unsubscribe();
+                };
+                req.on("close", cleanup);
+                res.on("close", cleanup);
+                return;
+            }
+            errorResponse(res, 404, "not_found", `Unknown endpoint: ${pathname}`);
+        })().catch((error) => {
+            if (!res.headersSent) {
+                errorResponse(res, 500, "internal_error", error.message);
+                return;
+            }
+            res.destroy(error);
+        });
+    });
+    server.on("connection", (socket) => {
+        sockets.add(socket);
+        socket.on("close", () => {
+            sockets.delete(socket);
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(requestedPort, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        throw new Error("Runner API failed to bind to an address");
+    }
+    const { port } = address;
+    store.setBinding("127.0.0.1", port);
+    return {
+        port,
+        close: () => new Promise((resolve, reject) => {
+            for (const socket of sockets) {
+                socket.destroy();
+            }
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        }),
+    };
+}

package/dist/runnerSession.d.ts

@@ -0,0 +1,62 @@
+import type { ApprovalDecisionPayload, ApprovalRequest, RunEvent, RunController, RunObserver, RunnerEventEnvelope, RunnerLogChunk, RunnerSessionInfo, RunSnapshot, StepDetailSnapshot, WorkflowDefinition } from "./types.js";
+interface RunnerSessionStoreOptions {
+    runId: string;
+    workflow: WorkflowDefinition;
+    objective: string;
+    objectives: string[];
+    host?: string;
+    port?: number;
+    attachToken?: string;
+    startedAt?: string;
+    sessionId?: string;
+}
+interface LogListResult {
+    items: RunnerLogChunk[];
+    nextCursor: string | null;
+}
+type Subscriber = (event: RunnerEventEnvelope) => void;
+export declare class RunnerSessionStore implements RunObserver, RunController {
+    private readonly workflow;
+    private readonly subscribers;
+    private readonly maxLogChunks;
+    private snapshotState;
+    private stepDetailsState;
+    private readonly eventHistory;
+    private readonly logHistory;
+    private readonly sessionState;
+    private pendingApproval;
+    constructor(options: RunnerSessionStoreOptions);
+    setBinding(host: string, port: number): void;
+    sessionInfo(): RunnerSessionInfo;
+    attachToken(): string;
+    runId(): string;
+    snapshot(): RunSnapshot;
+    stepDetail(stepKey: string): StepDetailSnapshot | null;
+    listLogs(stepKey?: string, limit?: number, cursor?: string): LogListResult;
+    events(sinceSequence?: number, includeLogs?: boolean): RunnerEventEnvelope[];
+    subscribe(listener: Subscriber): () => void;
+    onEvent(event: RunEvent): void;
+    onSnapshot(snapshot: RunSnapshot, stepDetails: StepDetailSnapshot[]): void;
+    onLog(log: RunnerLogChunk): void;
+    publicSession(): Omit<RunnerSessionInfo, "attachToken">;
+    isKnownRun(runId: string): boolean;
+    workflowDefinition(): WorkflowDefinition;
+    waitForDecision(request: ApprovalRequest): Promise<ApprovalDecisionPayload>;
+    approve(stepKey?: string, metadata?: Omit<ApprovalDecisionPayload, "decision">): {
+        ok: boolean;
+        reason?: string;
+        stepKey?: string;
+    };
+    resume(stepKey?: string, metadata?: Omit<ApprovalDecisionPayload, "decision">): {
+        ok: boolean;
+        reason?: string;
+        stepKey?: string;
+    };
+    cancel(stepKey?: string, metadata?: Omit<ApprovalDecisionPayload, "decision">): {
+        ok: boolean;
+        reason?: string;
+        stepKey?: string;
+    };
+    private resolvePendingApproval;
+}
+export {};

package/dist/runnerSession.js

@@ -0,0 +1,260 @@
+import { randomUUID } from "node:crypto";
+import { resolveTaskAdapter } from "./adapters.js";
+function contextSummary(value) {
+    if (typeof value === "string") {
+        return { type: "string", length: value.length };
+    }
+    if (value && typeof value === "object") {
+        return { type: "object", keys: Object.keys(value).sort() };
+    }
+    return { type: "none" };
+}
+function stepConfig(step) {
+    return {
+        model: typeof step.taskSpec?.init?.model === "string" ? step.taskSpec.init.model : null,
+        skills: step.taskSpec?.init?.skills ?? [],
+        mcps: step.taskSpec?.init?.mcps ?? [],
+        systemPrompts: step.taskSpec?.init?.systemPrompts ?? [],
+        contextSummary: contextSummary(step.taskSpec?.init?.context),
+    };
+}
+function cloneSnapshot(snapshot) {
+    return {
+        ...snapshot,
+        objectives: [...snapshot.objectives],
+        waitingForApproval: snapshot.waitingForApproval
+            ? {
+                ...snapshot.waitingForApproval,
+                preview: snapshot.waitingForApproval.preview
+                    ? {
+                        ...snapshot.waitingForApproval.preview,
+                        items: snapshot.waitingForApproval.preview.items.map((item) => ({ ...item })),
+                    }
+                    : null,
+            }
+            : null,
+        steps: snapshot.steps.map((step) => ({ ...step })),
+    };
+}
+function cloneStepDetails(stepDetails) {
+    return stepDetails.map((detail) => ({
+        ...detail,
+        dependsOn: [...detail.dependsOn],
+        config: {
+            ...detail.config,
+            skills: [...detail.config.skills],
+            mcps: [...detail.config.mcps],
+            systemPrompts: [...detail.config.systemPrompts],
+            contextSummary: {
+                ...detail.config.contextSummary,
+                keys: detail.config.contextSummary.keys ? [...detail.config.contextSummary.keys] : undefined,
+            },
+        },
+        lastExecution: { ...detail.lastExecution },
+    }));
+}
+function envelopeFromEvent(event) {
+    return {
+        id: event.id,
+        sequence: event.sequenceNumber,
+        type: event.type,
+        runId: event.runId,
+        stepKey: event.stepRunId,
+        occurredAt: event.occurredAt,
+        data: { ...event.payload },
+    };
+}
+export class RunnerSessionStore {
+    workflow;
+    subscribers = new Set();
+    maxLogChunks = 2000;
+    snapshotState;
+    stepDetailsState;
+    eventHistory = [];
+    logHistory = [];
+    sessionState;
+    pendingApproval = null;
+    constructor(options) {
+        this.workflow = options.workflow;
+        const startedAt = options.startedAt ?? new Date().toISOString();
+        const host = options.host ?? "127.0.0.1";
+        const port = options.port ?? 0;
+        const attachToken = options.attachToken ?? randomUUID();
+        const steps = options.workflow.steps.map((step) => ({
+            stepKey: step.key,
+            status: "pending",
+            attempt: 0,
+            confirmed: false,
+            adapter: step.kind === "task" ? resolveTaskAdapter(step.taskSpec?.adapterKey) : "approval",
+            startedAt: null,
+            updatedAt: startedAt,
+            finishedAt: null,
+        }));
+        const emptyExecution = {
+            executionStatus: null,
+            qaAction: null,
+            feedbackReason: null,
+        };
+        this.stepDetailsState = options.workflow.steps.map((step, index) => ({
+            ...steps[index],
+            kind: step.kind,
+            objective: step.objective ?? step.title ?? null,
+            dependsOn: step.dependsOn ?? [],
+            config: stepConfig(step),
+            lastExecution: { ...emptyExecution },
+        }));
+        this.snapshotState = {
+            runId: options.runId,
+            workflowKey: options.workflow.key,
+            workflowTitle: options.workflow.title,
+            status: "queued",
+            currentStepKey: null,
+            startedAt: null,
+            updatedAt: startedAt,
+            endedAt: null,
+            objective: options.objective,
+            objectives: [...options.objectives],
+            waitingForApproval: null,
+            steps,
+        };
+        this.sessionState = {
+            sessionId: options.sessionId ?? randomUUID(),
+            pid: process.pid,
+            host,
+            port,
+            baseUrl: `http://${host}:${port}`,
+            attachToken,
+            startedAt,
+            run: {
+                runId: options.runId,
+                workflowKey: options.workflow.key,
+                workflowTitle: options.workflow.title,
+                status: "queued",
+            },
+        };
+    }
+    setBinding(host, port) {
+        this.sessionState.host = host;
+        this.sessionState.port = port;
+        this.sessionState.baseUrl = `http://${host}:${port}`;
+    }
+    sessionInfo() {
+        return {
+            ...this.sessionState,
+            run: { ...this.sessionState.run },
+        };
+    }
+    attachToken() {
+        return this.sessionState.attachToken;
+    }
+    runId() {
+        return this.snapshotState.runId;
+    }
+    snapshot() {
+        return cloneSnapshot(this.snapshotState);
+    }
+    stepDetail(stepKey) {
+        const detail = this.stepDetailsState.find((step) => step.stepKey === stepKey);
+        if (!detail) {
+            return null;
+        }
+        return cloneStepDetails([detail])[0] ?? null;
+    }
+    listLogs(stepKey, limit = 200, cursor) {
+        const parsedLimit = Number.isFinite(limit) ? Math.max(1, Math.floor(limit)) : 200;
+        const filtered = stepKey ? this.logHistory.filter((log) => log.stepKey === stepKey) : this.logHistory;
+        const offset = cursor ? Math.max(0, Number.parseInt(cursor, 10) || 0) : 0;
+        const items = filtered.slice(offset, offset + parsedLimit).map((item) => ({ ...item }));
+        const nextCursor = offset + parsedLimit < filtered.length ? String(offset + parsedLimit) : null;
+        return { items, nextCursor };
+    }
+    events(sinceSequence, includeLogs = true) {
+        return this.eventHistory
+            .filter((event) => (sinceSequence ? event.sequence > sinceSequence : true))
+            .filter((event) => includeLogs || (event.type !== "agent.stdout" && event.type !== "agent.stderr"))
+            .map((event) => ({ ...event, data: { ...event.data } }));
+    }
+    subscribe(listener) {
+        this.subscribers.add(listener);
+        return () => {
+            this.subscribers.delete(listener);
+        };
+    }
+    onEvent(event) {
+        const envelope = envelopeFromEvent(event);
+        this.eventHistory.push(envelope);
+        for (const subscriber of this.subscribers) {
+            subscriber(envelope);
+        }
+    }
+    onSnapshot(snapshot, stepDetails) {
+        this.snapshotState = cloneSnapshot(snapshot);
+        this.stepDetailsState = cloneStepDetails(stepDetails);
+        this.sessionState.run.status = snapshot.status;
+    }
+    onLog(log) {
+        this.logHistory.push({ ...log });
+        if (this.logHistory.length > this.maxLogChunks) {
+            this.logHistory.splice(0, this.logHistory.length - this.maxLogChunks);
+        }
+    }
+    publicSession() {
+        const { attachToken: _attachToken, ...publicInfo } = this.sessionInfo();
+        return publicInfo;
+    }
+    isKnownRun(runId) {
+        return this.snapshotState.runId === runId;
+    }
+    workflowDefinition() {
+        return this.workflow;
+    }
+    waitForDecision(request) {
+        if (this.pendingApproval?.stepKey === request.stepKey) {
+            return this.pendingApproval.promise;
+        }
+        let resolveDecision;
+        const promise = new Promise((resolve) => {
+            resolveDecision = resolve;
+        });
+        this.pendingApproval = {
+            ...request,
+            promise,
+            resolve: resolveDecision,
+        };
+        return promise;
+    }
+    approve(stepKey, metadata = {}) {
+        return this.resolvePendingApproval("approved", stepKey, metadata, "human");
+    }
+    resume(stepKey, metadata = {}) {
+        return this.resolvePendingApproval("approved", stepKey, metadata, "external");
+    }
+    cancel(stepKey, metadata = {}) {
+        return this.resolvePendingApproval("cancelled", stepKey, metadata);
+    }
+    resolvePendingApproval(decision, stepKey, metadata = {}, expectedValidation) {
+        if (!this.pendingApproval) {
+            return { ok: false, reason: "No step is waiting for approval" };
+        }
+        if (stepKey && this.pendingApproval.stepKey !== stepKey) {
+            return {
+                ok: false,
+                reason: `Step ${stepKey} is not currently waiting for approval`,
+            };
+        }
+        // Waits with validation "none" (or unset) declare no expected resolution verb,
+        // so both approve and resume must be able to release them.
+        const pendingValidation = this.pendingApproval.validation ?? "none";
+        if (expectedValidation && pendingValidation !== "none" && pendingValidation !== expectedValidation) {
+            const action = expectedValidation === "external" ? "resume" : "approve";
+            return {
+                ok: false,
+                reason: `Cannot ${action} ${pendingValidation} validation for ${this.pendingApproval.stepKey}`,
+            };
+        }
+        const pending = this.pendingApproval;
+        this.pendingApproval = null;
+        pending.resolve({ decision, ...metadata });
+        return { ok: true, stepKey: pending.stepKey };
+    }
+}

package/dist/runtimePreflight.d.ts

@@ -0,0 +1,16 @@
+import type { AdapterKey, WorkflowDefinition } from "./types.js";
+export interface RuntimeDoctorCheck {
+    key: string;
+    label: string;
+    status: "ok" | "missing" | "info";
+    required: boolean;
+    detail: string;
+}
+export interface AdapterImplementationStatus {
+    adapter: AdapterKey;
+    status: "real" | "mock" | "partial";
+    detail: string;
+}
+export declare function validateRuntimeRequirements(definition: WorkflowDefinition, env?: NodeJS.ProcessEnv): string[];
+export declare function runtimeDoctorChecks(env?: NodeJS.ProcessEnv): RuntimeDoctorCheck[];
+export declare function adapterImplementationStatuses(): AdapterImplementationStatus[];