@ryanfw/prompt-orchestration-pipeline 1.3.2 → 1.3.4

package/src/core/job-view.ts

@@ -0,0 +1,473 @@
+import {
+  JOB_STATUS_SYNONYMS,
+  VALID_JOB_STATUSES,
+  deriveJobStatusFromTasks,
+  jobStateToStatus,
+  normalizeJobStatus,
+  normalizeTaskState,
+} from "../config/statuses.ts";
+import type { JobStatusValue, TaskStateValue } from "../config/statuses.ts";
+import type { UsageSource } from "../providers/types.ts";
+import type { GateInfo } from "./status-writer.ts";
+
+export type RetryError = { message: string; name?: string; stack?: string } | string;
+
+export interface JobViewError {
+  code: string;
+  message: string;
+  path?: string;
+  name?: string;
+  stack?: string;
+}
+
+export interface JobViewTask {
+  state: TaskStateValue;
+  name: string;
+  files: { artifacts: string[]; logs: string[]; tmp: string[] };
+  startedAt?: string | null;
+  endedAt?: string | null;
+  attempts?: number;
+  restartCount?: number;
+  retrying?: boolean;
+  nextRetryAt?: string;
+  lastRetryError?: RetryError | null;
+  executionTimeMs?: number;
+  refinementAttempts?: number;
+  stageLogPath?: string;
+  errorContext?: unknown;
+  currentStage?: string;
+  failedStage?: string;
+  artifacts?: unknown;
+  tokenUsage?: unknown[];
+  error?: { message: string; [key: string]: unknown } | null;
+  skipReason?: string;
+  skippedBy?: string;
+  controlApplied?: boolean;
+}
+
+export interface JobView {
+  id: string;
+  jobId: string;
+  name: string;
+  title: string;
+  status: JobStatusValue;
+  progress: number;
+  createdAt: string | null;
+  updatedAt: string | null;
+  lastUpdated?: string;
+  location: string | null;
+  tasks: Record<string, JobViewTask>;
+  files: Record<string, unknown>;
+  costs: Record<string, unknown>;
+  gate?: GateInfo | null;
+  pipeline?: string;
+  pipelineLabel?: string;
+  pipelineConfig?: Record<string, unknown>;
+  current?: unknown;
+  currentStage?: unknown;
+  warnings?: string[];
+  readable?: boolean;
+  error?: JobViewError;
+  errorContext?: unknown;
+}
+
+interface TaskFilesView {
+  artifacts: string[];
+  logs: string[];
+  tmp: string[];
+}
+
+const EMPTY_TASK_FILES: TaskFilesView = { artifacts: [], logs: [], tmp: [] };
+const DEFAULT_JOB_ERROR_CODE = "JOB_ERROR";
+
+export interface DerivedProgress {
+  taskCount: number;
+  doneCount: number;
+  completedCount: number;
+  progress: number;
+}
+
+export function deriveProgress(
+  tasks: ReadonlyArray<{ state?: string }>,
+  configuredCount: number | null,
+): DerivedProgress {
+  const actual = tasks.length;
+  const doneCount = tasks.filter((task) => task.state === "done").length;
+  const completedCount = tasks.filter(
+    (task) => task.state === "done" || task.state === "skipped",
+  ).length;
+  const taskCount = Math.max(configuredCount ?? 0, actual);
+  const progress = taskCount === 0
+    ? 0
+    : Math.min(100, Math.floor((completedCount / taskCount) * 100));
+  return { taskCount, doneCount, completedCount, progress };
+}
+
+const warnedFallbackKeys = new Set<string>();
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isRecognizedStatusValue(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const normalized = value.toLowerCase().trim();
+  if (Object.prototype.hasOwnProperty.call(JOB_STATUS_SYNONYMS, normalized)) return true;
+  return VALID_JOB_STATUSES.has(normalized);
+}
+
+function toStringOrNull(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function toStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === "string");
+}
+
+function toFiniteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function toTaskFiles(value: unknown): TaskFilesView {
+  if (!isRecord(value)) return { ...EMPTY_TASK_FILES };
+  return {
+    artifacts: toStringArray(value["artifacts"]),
+    logs: toStringArray(value["logs"]),
+    tmp: toStringArray(value["tmp"]),
+  };
+}
+
+function toTaskError(value: unknown): JobViewTask["error"] {
+  if (value === null) return null;
+  if (typeof value === "string") return { message: value };
+  if (isRecord(value)) return value as { message: string; [key: string]: unknown };
+  return undefined;
+}
+
+function toGateInfo(value: unknown): GateInfo | null | undefined {
+  if (value === null) return null;
+  if (!isRecord(value)) return undefined;
+  const rawArtifacts = value["artifacts"];
+  const artifacts = Array.isArray(rawArtifacts)
+    ? rawArtifacts.filter((entry): entry is string => typeof entry === "string")
+    : undefined;
+  const rawKind = value["kind"];
+  const kind = rawKind === "approval" || rawKind === "control_invalid" ? rawKind : undefined;
+  return {
+    afterTask: typeof value["afterTask"] === "string" ? value["afterTask"] : "",
+    message: typeof value["message"] === "string" ? value["message"] : "",
+    requestedAt: typeof value["requestedAt"] === "string" ? value["requestedAt"] : "",
+    ...(kind ? { kind } : {}),
+    ...(artifacts && artifacts.length > 0 ? { artifacts } : {}),
+  };
+}
+
+function toJobViewTask(name: string, value: unknown): JobViewTask {
+  const task = isRecord(value) ? value : {};
+  return {
+    name,
+    state: normalizeTaskState(task["state"]),
+    files: toTaskFiles(task["files"]),
+    startedAt: toStringOrNull(task["startedAt"]),
+    endedAt: toStringOrNull(task["endedAt"]),
+    attempts: typeof task["attempts"] === "number" ? task["attempts"] : undefined,
+    restartCount: typeof task["restartCount"] === "number" ? task["restartCount"] : undefined,
+    retrying: typeof task["retrying"] === "boolean" ? task["retrying"] : undefined,
+    nextRetryAt: typeof task["nextRetryAt"] === "string" ? task["nextRetryAt"] : undefined,
+    lastRetryError: Object.hasOwn(task, "lastRetryError")
+      ? (task["lastRetryError"] as RetryError | null)
+      : undefined,
+    executionTimeMs: typeof task["executionTimeMs"] === "number"
+      ? task["executionTimeMs"]
+      : undefined,
+    refinementAttempts: typeof task["refinementAttempts"] === "number"
+      ? task["refinementAttempts"]
+      : undefined,
+    stageLogPath: typeof task["stageLogPath"] === "string" ? task["stageLogPath"] : undefined,
+    errorContext: task["errorContext"],
+    currentStage: typeof task["currentStage"] === "string" ? task["currentStage"] : undefined,
+    failedStage: typeof task["failedStage"] === "string" ? task["failedStage"] : undefined,
+    artifacts: task["artifacts"],
+    tokenUsage: Array.isArray(task["tokenUsage"]) ? task["tokenUsage"] : undefined,
+    error: toTaskError(task["error"]),
+    skipReason: typeof task["skipReason"] === "string" ? task["skipReason"] : undefined,
+    skippedBy: typeof task["skippedBy"] === "string" ? task["skippedBy"] : undefined,
+    controlApplied: typeof task["controlApplied"] === "boolean" ? task["controlApplied"] : undefined,
+  };
+}
+
+function toJobViewTasks(value: unknown): Record<string, JobViewTask> {
+  if (Array.isArray(value)) {
+    return Object.fromEntries(
+      value.map((entry, index) => {
+        const record = isRecord(entry) ? entry : {};
+        const explicitName = record["name"];
+        const name = typeof explicitName === "string" && explicitName.length > 0
+          ? explicitName
+          : `task-${index}`;
+        return [name, toJobViewTask(name, record)] as const;
+      }),
+    );
+  }
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([name, entry]) => [name, toJobViewTask(name, entry)] as const),
+    );
+  }
+  return {};
+}
+
+function getRawTaskNameValuePairs(value: unknown): Array<[string, unknown]> {
+  if (Array.isArray(value)) {
+    return value.map((entry, index) => {
+      const record = isRecord(entry) ? entry : {};
+      const explicitName = record["name"];
+      const name = typeof explicitName === "string" && explicitName.length > 0
+        ? explicitName
+        : `task-${index}`;
+      return [name, entry] as [string, unknown];
+    });
+  }
+  if (isRecord(value)) {
+    return Object.entries(value);
+  }
+  return [];
+}
+
+function readUsageSource(value: unknown): UsageSource {
+  return value === "reported" ||
+      value === "estimated" ||
+      value === "unavailable" ||
+      value === "zero"
+    ? value
+    : "reported";
+}
+
+const SOURCE_RANK: Record<UsageSource, number> = {
+  reported: 0,
+  zero: 0,
+  estimated: 1,
+  unavailable: 2,
+};
+
+function combineSource(current: UsageSource | undefined, next: UsageSource): UsageSource {
+  if (current === undefined) return next;
+  return SOURCE_RANK[current] >= SOURCE_RANK[next] ? current : next;
+}
+
+function readCostEstimated(entry: unknown[], source: UsageSource): boolean {
+  if (typeof entry[6] === "boolean") return entry[6];
+  if (source === "estimated" || source === "unavailable") return true;
+  return false;
+}
+
+interface TaskCostBreakdownEntry {
+  inputTokens: number;
+  outputTokens: number;
+  inputCost: number;
+  outputCost: number;
+  totalCost: number;
+  source?: UsageSource;
+  failed?: true;
+  costEstimated?: true;
+}
+
+function getCosts(record: Record<string, unknown>): Record<string, unknown> {
+  const explicitCosts = record["costs"];
+  if (isRecord(explicitCosts)) return explicitCosts;
+
+  let totalCost = 0;
+  let estimatedCost = 0;
+  let unavailableCost = 0;
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  let hasEstimated = false;
+  const breakdown: Record<string, TaskCostBreakdownEntry> = {};
+
+  for (const [name, value] of getRawTaskNameValuePairs(record["tasks"])) {
+    if (!isRecord(value)) continue;
+    const usage = value["tokenUsage"];
+    if (!Array.isArray(usage)) continue;
+
+    let taskInputTokens = 0;
+    let taskOutputTokens = 0;
+    let taskReportedCost = 0;
+    let taskEstimatedCost = 0;
+    let taskUnavailableCost = 0;
+    let taskSource: UsageSource | undefined;
+    let taskFailed: true | undefined;
+    let taskCostEstimated = false;
+    let contributed = false;
+
+    for (const entry of usage) {
+      if (!Array.isArray(entry)) continue;
+      contributed = true;
+      const inputTokens = toFiniteNumber(entry[1]) ?? 0;
+      const outputTokens = toFiniteNumber(entry[2]) ?? 0;
+      const cost = toFiniteNumber(entry[3]) ?? 0;
+      const source = readUsageSource(entry[4]);
+      const failed = entry[5] === true;
+      const costEstimated = readCostEstimated(entry, source);
+
+      taskInputTokens += inputTokens;
+      taskOutputTokens += outputTokens;
+      totalInputTokens += inputTokens;
+      totalOutputTokens += outputTokens;
+
+      if (source === "unavailable") {
+        unavailableCost += cost;
+        taskUnavailableCost += cost;
+        hasEstimated = true;
+      } else if (costEstimated) {
+        estimatedCost += cost;
+        taskEstimatedCost += cost;
+        hasEstimated = true;
+      } else {
+        totalCost += cost;
+        taskReportedCost += cost;
+      }
+
+      taskSource = combineSource(taskSource, source);
+      if (failed) taskFailed = true;
+      if (costEstimated) {
+        hasEstimated = true;
+        taskCostEstimated = true;
+      }
+    }
+
+    if (!contributed) continue;
+
+    const entry: TaskCostBreakdownEntry = {
+      inputTokens: taskInputTokens,
+      outputTokens: taskOutputTokens,
+      inputCost: 0,
+      outputCost: 0,
+      totalCost: taskReportedCost + taskEstimatedCost + taskUnavailableCost,
+    };
+    if (taskSource !== undefined) entry.source = taskSource;
+    if (taskFailed === true) entry.failed = true;
+    if (taskCostEstimated) entry.costEstimated = true;
+    breakdown[name] = entry;
+  }
+
+  const totalTokens = totalInputTokens + totalOutputTokens;
+  if (
+    totalTokens === 0 &&
+    totalCost === 0 &&
+    estimatedCost === 0 &&
+    unavailableCost === 0
+  ) {
+    return {};
+  }
+  return {
+    totalCost,
+    totalTokens,
+    totalInputTokens,
+    totalOutputTokens,
+    estimatedCost,
+    unavailableCost,
+    hasEstimated,
+    ...breakdown,
+  };
+}
+
+function resolveStateStatus(
+  fromState: JobStatusValue,
+  tasks: JobViewTask[],
+  location: string,
+): JobStatusValue {
+  if (fromState !== "complete" || location === "complete" || tasks.length === 0) {
+    return fromState;
+  }
+
+  const taskStatus = deriveJobStatusFromTasks(tasks);
+  return taskStatus === "complete" ? fromState : taskStatus;
+}
+
+function toTitle(record: Record<string, unknown>, fallback: string): string {
+  const candidate = record["title"] ?? record["name"];
+  return typeof candidate === "string" && candidate.length > 0 ? candidate : fallback;
+}
+
+function toErrorView(value: unknown): JobViewError | undefined {
+  if (!isRecord(value)) return undefined;
+  if (typeof value["message"] !== "string") return undefined;
+  const code = typeof value["code"] === "string"
+    ? value["code"]
+    : typeof value["name"] === "string"
+      ? value["name"]
+      : DEFAULT_JOB_ERROR_CODE;
+  const result: JobViewError = { code, message: value["message"] };
+  if (typeof value["path"] === "string") result.path = value["path"];
+  if (typeof value["name"] === "string") result.name = value["name"];
+  if (typeof value["stack"] === "string") result.stack = value["stack"];
+  return result;
+}
+
+export function normalizeJobView(raw: unknown, jobId: string, location: string): JobView {
+  const record = isRecord(raw) ? raw : {};
+
+  const tasks = toJobViewTasks(record["tasks"]);
+  const taskList = Object.values(tasks);
+  const pipelineConfig = isRecord(record["pipelineConfig"]) ? record["pipelineConfig"] : null;
+  const configuredTaskCount = pipelineConfig && Array.isArray(pipelineConfig["tasks"])
+    ? pipelineConfig["tasks"].length
+    : null;
+
+  const fromState = jobStateToStatus(record["state"]);
+  let status: JobStatusValue;
+  if (fromState !== null) {
+    status = resolveStateStatus(fromState, taskList, location);
+  } else if (isRecognizedStatusValue(record["status"])) {
+    status = normalizeJobStatus(record["status"]);
+  } else {
+    const warnKey = `${location}:${jobId}`;
+    if (!warnedFallbackKeys.has(warnKey)) {
+      warnedFallbackKeys.add(warnKey);
+      console.warn(
+        `normalizeJobView: no valid state or status for ${warnKey}; deriving job status from tasks.`,
+      );
+    }
+    status = deriveJobStatusFromTasks(taskList);
+  }
+
+  const title = toTitle(record, jobId);
+  const lastUpdated = toStringOrNull(record["lastUpdated"]);
+
+  const result: JobView = {
+    id: jobId,
+    jobId,
+    name: title,
+    title,
+    status,
+    progress: deriveProgress(taskList, configuredTaskCount).progress,
+    createdAt: toStringOrNull(record["createdAt"]),
+    updatedAt: toStringOrNull(record["updatedAt"]) ?? lastUpdated,
+    location,
+    tasks,
+    files: isRecord(record["files"]) ? record["files"] : {},
+    costs: getCosts(record),
+  };
+
+  if (lastUpdated !== null) result.lastUpdated = lastUpdated;
+  if ("gate" in record) result.gate = toGateInfo(record["gate"]);
+  if (typeof record["pipeline"] === "string") result.pipeline = record["pipeline"];
+  if (typeof record["pipelineLabel"] === "string") result.pipelineLabel = record["pipelineLabel"];
+  if (pipelineConfig) result.pipelineConfig = pipelineConfig;
+  if ("current" in record) result.current = record["current"];
+  if ("currentStage" in record) result.currentStage = record["currentStage"];
+  if (Array.isArray(record["warnings"])) {
+    result.warnings = record["warnings"].filter((entry): entry is string => typeof entry === "string");
+  }
+  if (typeof record["readable"] === "boolean") result.readable = record["readable"];
+  const errorView = toErrorView(record["error"]);
+  if (errorView) result.error = errorView;
+  if ("errorContext" in record) result.errorContext = record["errorContext"];
+
+  return result;
+}
+
+export function __resetWarnedFallbackKeys(): void {
+  warnedFallbackKeys.clear();
+}

package/src/core/json-file.ts

@@ -0,0 +1,45 @@
+import { atomicWrite } from "./status-writer";
+
+function causeDetail(cause: unknown): string {
+  if (cause instanceof Error) {
+    const code = (cause as NodeJS.ErrnoException).code;
+    return code ? `${code}: ${cause.message}` : cause.message;
+  }
+  return String(cause);
+}
+
+export class JsonFileError extends Error {
+  readonly path: string;
+  readonly reason: "missing" | "parse";
+  constructor(path: string, reason: "missing" | "parse", cause?: unknown) {
+    super(`JSON file ${reason} at ${path}: ${causeDetail(cause)}`, { cause });
+    this.name = "JsonFileError";
+    this.path = path;
+    this.reason = reason;
+  }
+}
+
+export async function readJsonFile<T>(filePath: string): Promise<T> {
+  let text: string;
+  try {
+    text = await Bun.file(filePath).text();
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new JsonFileError(filePath, "missing", err);
+    }
+    throw err;
+  }
+
+  try {
+    return JSON.parse(text) as T;
+  } catch (err: unknown) {
+    if (err instanceof SyntaxError) {
+      throw new JsonFileError(filePath, "parse", err);
+    }
+    throw err;
+  }
+}
+
+export async function writeJsonFile(filePath: string, value: unknown): Promise<void> {
+  await atomicWrite(filePath, JSON.stringify(value, null, 2) + "\n");
+}

package/src/core/lifecycle-policy.ts

@@ -1,3 +1,5 @@
+import { normalizeTaskState } from "../config/statuses";
+
 type LifecycleOp = "start" | "restart";
 
 interface TransitionInput {
@@ -13,7 +15,7 @@ interface TransitionAllowed {
 interface TransitionBlocked {
   ok: false;
   code: "unsupported_lifecycle";
-  reason: "dependencies" | "policy";
+  reason: "dependencies";
 }
 
 type TransitionDecision = TransitionAllowed | TransitionBlocked;
@@ -24,11 +26,24 @@ const BLOCKED_DEPS: Readonly<TransitionBlocked> = Object.freeze({
   code: "unsupported_lifecycle" as const,
   reason: "dependencies" as const,
 });
-const BLOCKED_POLICY: Readonly<TransitionBlocked> = Object.freeze({
-  ok: false as const,
-  code: "unsupported_lifecycle" as const,
-  reason: "policy" as const,
-});
+
+export function areDependenciesSatisfied(predecessorStates: Iterable<string>): boolean {
+  for (const state of predecessorStates) {
+    const normalized = normalizeTaskState(state);
+    if (normalized !== "done" && normalized !== "skipped") return false;
+  }
+  return true;
+}
+
+export function firstUnsatisfiedDependency(
+  predecessors: ReadonlyArray<{ name: string; state: string }>,
+): { name: string; state: string } | null {
+  for (const predecessor of predecessors) {
+    const normalized = normalizeTaskState(predecessor.state);
+    if (normalized !== "done" && normalized !== "skipped") return predecessor;
+  }
+  return null;
+}
 
 export function decideTransition(input: TransitionInput): Readonly<TransitionDecision> {
   const { op, taskState, dependenciesReady } = input;
@@ -47,6 +62,6 @@ export function decideTransition(input: TransitionInput): Readonly<TransitionDec
     return dependenciesReady ? ALLOWED : BLOCKED_DEPS;
   }
 
-  // op === "restart": only allowed from "done" state, ignores dependenciesReady
-  return taskState === "done" ? ALLOWED : BLOCKED_POLICY;
+  // op === "restart": gated on dependenciesReady (same rule as "start")
+  return dependenciesReady ? ALLOWED : BLOCKED_DEPS;
 }

package/src/core/logger.ts

@@ -17,25 +17,6 @@ export interface Logger {
   sse(eventType: string, eventData: unknown): void;
 }
 
-// Lazy SSE registry cache
-let sseRegistry: { broadcast: (eventType: string, data: unknown) => void } | null = null;
-
-async function getSSERegistry(): Promise<{ broadcast: (eventType: string, data: unknown) => void } | null> {
-  if (sseRegistry !== null) return sseRegistry;
-  try {
-    // Dynamic import path kept as a variable to avoid static resolution errors
-    // when the module does not yet exist. Fails gracefully at runtime.
-    const ssePath = "../ui/sse.ts";
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-    const mod = await import(/* @vite-ignore */ ssePath);
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-    sseRegistry = mod as { broadcast: (eventType: string, data: unknown) => void };
-    return sseRegistry;
-  } catch {
-    return null;
-  }
-}
-
 function formatPrefix(componentName: string, context?: LogContext): string {
   const parts: string[] = [componentName];
   if (context?.jobId) parts.push(context.jobId);
@@ -124,16 +105,6 @@ export function createLogger(componentName: string, context?: LogContext): Logge
 
     sse(eventType, eventData) {
       console.log(prefix, `[SSE:${eventType}]`, stringify(eventData));
-      void getSSERegistry().then((registry) => {
-        if (!registry) return;
-        try {
-          registry.broadcast(eventType, formatData(eventData));
-        } catch (err) {
-          console.warn(prefix, "SSE broadcast failed", err);
-        }
-      }).catch((err) => {
-        console.warn(prefix, "SSE registry unavailable", err);
-      });
     },
   };
 }