@hilbras/omninode 2.0.0-alpha.4 → 2.0.0-alpha.5

package/README.md

@@ -18,9 +18,9 @@ existing intelligence; it does not try to become another model.
 
 ## Status
 
-**v2.0.0-alpha.4 — v2 Phase 4: Agent Adapter Hardening**
-(after Phase 1: architecture & API stabilization, Phase 2: execution reliability,
-Phase 3: agent protocol v2 — the reliability & interoperability line) (the v2
+**v2.0.0-alpha.5 — v2 Phase 5: Pipeline Lifecycle v2**
+(the reliability & interoperability line: architecture → execution →
+protocol → adapters → pipelines) (the v2
 roadmap is [docs/ROADMAP_V2.md](docs/ROADMAP_V2.md); the v1 plan is complete:
 the
 full loop from §28 runs in one command —
@@ -31,6 +31,13 @@ for the plan and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design).
 
 ### What's new in v2 (so far)
 
+- **Phase 5 — Pipeline Lifecycle**: first-class pipeline cancellation
+  (`omninode pipeline cancel <run-id>`: stop scheduling → cancel running
+  tasks → terminate agent processes → persist a `cancelled` run), `pipeline
+  validate` for pre-run checks (deps, cycles, agents, model references),
+  explicit run/step **attempts** in the run record, the
+  `IPipelineExecutor` contract, and recovery awareness — runs left `running`
+  without a `finishedAt` are flagged as interrupted in `pipeline runs`.
 - **Phase 4 — Agent Adapter Hardening**: process-tree cleanup (agents run in
   their own process group; timeout, cancel and Ctrl-C reap the whole tree, so
   no orphaned children), explicit environment policies

package/dist/cli/index.js

@@ -6,7 +6,7 @@ import { realpathSync } from "fs";
 import { Command } from "commander";
 
 // src/version.ts
-var OMNINODE_VERSION = "2.0.0-alpha.4";
+var OMNINODE_VERSION = "2.0.0-alpha.5";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -1634,7 +1634,7 @@ function describeExit(code, signal) {
   return `Process exited with code ${code}.`;
 }
 function sanitizeChunk(chunk) {
-  return chunk.toString("utf8").replace(/\u0000/g, "");
+  return [...chunk.toString("utf8")].filter((char) => char.charCodeAt(0) !== 0).join("");
 }
 function normalizeReport(payload, taskId, agentName, index) {
   if (payload === null || typeof payload !== "object") return void 0;
@@ -2068,6 +2068,11 @@ var TaskEngine = class {
         if (this.options.memory) await this.options.memory.recordTaskOutcome(current);
         return current;
       }
+      const currentState = await this.options.store.get(current.id);
+      if (currentState?.status === "cancelled") {
+        current = currentState;
+        break;
+      }
       const result = {
         ...output.summary !== void 0 ? { summary: output.summary } : {},
         ...output.reports !== void 0 && output.reports.length > 0 ? { reports: output.reports } : {},
@@ -3193,9 +3198,23 @@ var PipelineEngine = class {
   }
   options;
   log;
+  /** Runs executing in THIS process — cancellation can terminate them directly. */
+  activeRuns = /* @__PURE__ */ new Map();
   get store() {
     return this.options.store;
   }
+  /**
+   * Saves the run while preserving fields that may be set by another process
+   * (e.g. a cancellation request) — an in-memory snapshot must never clobber
+   * externally requested cancellation (§9.2).
+   */
+  async persist(run2) {
+    const current = await this.options.store.get(run2.id);
+    await this.options.store.save({
+      ...run2,
+      ...current?.cancellationRequested === true ? { cancellationRequested: true, cancellationRequestedAt: current.cancellationRequestedAt } : {}
+    });
+  }
   /** Structural + semantic validation (§27 Phase 5 — pipeline parser). */
   validate(def) {
     const ids = /* @__PURE__ */ new Set();
@@ -3295,18 +3314,44 @@ var PipelineEngine = class {
           );
         }
       }
+      if (step.model) {
+        const separator = step.model.indexOf(":");
+        if (separator <= 0 || separator === step.model.length - 1) {
+          throw new PipelineError(
+            "PIPELINE_INVALID",
+            `Step "${step.id}" has an invalid model reference "${step.model}" \u2014 use "provider:model-id".`
+          );
+        }
+        const providerName = step.model.slice(0, separator);
+        if (!this.options.providers.some((p) => p.name === providerName)) {
+          throw new PipelineError(
+            "PIPELINE_INVALID",
+            `Step "${step.id}" uses model "${step.model}" but provider "${providerName}" is not configured.`
+          );
+        }
+      }
     }
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const run2 = {
       id: `run-${Date.now().toString(36)}-${randomBytes5(3).toString("hex")}`,
       pipelineId: def.id,
+      attempt: 1,
       objective,
       status: "running",
       startedAt: now,
       stepRuns: []
     };
     await this.options.store.save(run2);
-    this.log.info(`Running pipeline ${def.id} as ${run2.id}.`);
+    const liveTaskIds = /* @__PURE__ */ new Set();
+    this.activeRuns.set(run2.id, {
+      taskIds: liveTaskIds,
+      cancelTasks: async () => {
+        for (const taskId of liveTaskIds) {
+          await this.options.tasks.cancel(taskId).catch(() => void 0);
+        }
+      }
+    });
+    this.log.info(`Running pipeline ${def.id} as ${run2.id} (attempt ${run2.attempt}).`);
     await this.options.audit?.record({
       at: (/* @__PURE__ */ new Date()).toISOString(),
       action: "pipeline.run.started",
@@ -3318,7 +3363,22 @@ var PipelineEngine = class {
     const pending = new Set(def.steps.map((s) => s.id));
     const contextParts = [];
     const allReports = [];
+    let cancelled = false;
     while (pending.size > 0) {
+      const persisted = await this.options.store.get(run2.id);
+      if (persisted?.cancellationRequested === true) {
+        cancelled = true;
+        run2.cancellationRequested = true;
+        run2.cancellationRequestedAt = persisted.cancellationRequestedAt;
+        await this.activeRuns.get(run2.id)?.cancelTasks();
+        for (const step of def.steps.filter((s) => pending.has(s.id))) {
+          const stepRun = { stepId: step.id, status: "cancelled" };
+          run2.stepRuns.push(stepRun);
+          options.onStep?.(stepRun);
+        }
+        pending.clear();
+        break;
+      }
       const ready = def.steps.filter(
         (step) => pending.has(step.id) && (deps.get(step.id) ?? []).every((d) => outcomes.has(d))
       );
@@ -3335,7 +3395,8 @@ var PipelineEngine = class {
             ...role ? { role } : {},
             combinedContext: contextParts.join("\n\n"),
             reports: [...allReports],
-            pipelineRunId: run2.id
+            pipelineRunId: run2.id,
+            runId: run2.id
           };
           return this.executeStep(step, ctx);
         })
@@ -3352,6 +3413,8 @@ ${contribution}`);
         }
         const stepRun = {
           stepId: step.id,
+          attempt: outcome.attempt ?? 1,
+          ...outcome.executionIds && outcome.executionIds.length > 0 ? { executionIds: outcome.executionIds } : {},
           status: outcome.status === "skipped" ? "cancelled" : outcome.status === "failed" ? "failed" : outcome.status === "partial" ? "partially_completed" : "completed",
           ...outcome.taskIds.length > 0 ? { taskIds: outcome.taskIds } : {},
           ...outcome.planId !== void 0 ? { planId: outcome.planId } : {},
@@ -3361,12 +3424,12 @@ ${contribution}`);
         options.onStep?.(stepRun);
       });
       run2.reports = [...allReports];
-      await this.options.store.save(run2);
+      await this.persist(run2);
     }
     const allOutcomes = [...outcomes.values()];
-    const failed = allOutcomes.some((o) => o.status === "failed");
-    const partial = !failed && allOutcomes.some((o) => o.status === "partial");
-    const finalStatus = failed ? "failed" : partial ? "partial" : "completed";
+    const failed = !cancelled && allOutcomes.some((o) => o.status === "failed");
+    const partial = !cancelled && !failed && allOutcomes.some((o) => o.status === "partial");
+    const finalStatus = cancelled ? "cancelled" : failed ? "failed" : partial ? "partial" : "completed";
     const planId = [...outcomes.values()].find((o) => o.planId !== void 0)?.planId;
     let resultSummary;
     for (let i = def.steps.length - 1; i >= 0; i -= 1) {
@@ -3394,16 +3457,19 @@ ${contribution}`);
         run2.reports = collected;
       }
     }
+    const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.activeRuns.delete(run2.id);
     const finished = {
       ...run2,
       status: finalStatus,
-      finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      finishedAt,
+      attempts: [...run2.attempts ?? [], { attempt: run2.attempt, startedAt: run2.startedAt ?? finishedAt, finishedAt, status: finalStatus }],
       ...run2.reports !== void 0 && run2.reports.length > 0 ? { reports: run2.reports } : {},
       ...combinedReportId !== void 0 ? { combinedReportId } : {},
       ...planId !== void 0 ? { planId } : {},
       ...resultSummary !== void 0 ? { resultSummary } : {}
     };
-    await this.options.store.save(finished);
+    await this.persist(finished);
     this.log.info(`Pipeline ${def.id} finished: ${finalStatus}.`);
     await this.options.audit?.record({
       at: (/* @__PURE__ */ new Date()).toISOString(),
@@ -3413,6 +3479,23 @@ ${contribution}`);
     });
     return finished;
   }
+  /** First-class cancellation (§9.2): requests cancellation and terminates
+   *  tasks that are running in this process immediately. */
+  async cancel(runId) {
+    const run2 = await this.options.store.get(runId);
+    if (!run2) {
+      throw new PipelineError("PIPELINE_NOT_FOUND", `Pipeline run "${runId}" does not exist.`);
+    }
+    await this.options.store.save({
+      ...run2,
+      cancellationRequested: true,
+      cancellationRequestedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    const active = this.activeRuns.get(runId);
+    if (active) {
+      await active.cancelTasks();
+    }
+  }
   async get(runId) {
     return this.options.store.get(runId);
   }
@@ -3436,9 +3519,16 @@ ${contribution}`);
         this.log.warn(`Step "${step.id}" failed \u2014 retry ${attempt}/${retries}.`);
       }
       last = await this.executeStepOnce(step, ctx);
-      if (last.status !== "failed") return last;
+      if (last.status !== "failed") return { ...last, attempt: attempt + 1 };
     }
-    return last;
+    return { ...last, attempt: retries + 1 };
+  }
+  /** Registers tasks created for a step as live, so cancellation can terminate them (§9.2). */
+  trackLiveTasks(runId, taskIds) {
+    if (!runId) return;
+    const active = this.activeRuns.get(runId);
+    if (!active) return;
+    for (const id of taskIds) active.taskIds.add(id);
   }
   async executeStepOnce(step, ctx) {
     switch (step.kind) {
@@ -3471,7 +3561,9 @@ ${contribution}`);
         })
       )
     );
+    this.trackLiveTasks(ctx.runId, created.map((t) => t.id));
     const results = await Promise.all(created.map((task) => this.options.tasks.run(task.id)));
+    const executionIds = results.map((r) => r.executions?.at(-1)?.executionId).filter((id) => id !== void 0);
     const completedTasks = results.filter((r) => r.status === "completed");
     const failedTasks = results.filter((r) => r.status !== "completed");
     const lines = results.map((result, index) => {
@@ -3494,7 +3586,13 @@ ${contribution}`);
         reports
       };
     }
-    return { status: "completed", summary, taskIds: created.map((t) => t.id), reports };
+    return {
+      status: "completed",
+      summary,
+      taskIds: created.map((t) => t.id),
+      ...executionIds.length > 0 ? { executionIds } : {},
+      reports
+    };
   }
   async runSingle(step, ctx, agentName) {
     const task = await this.options.tasks.create({
@@ -3503,6 +3601,7 @@ ${contribution}`);
       ...ctx.role ? { role: ctx.role.id } : {},
       ...ctx.combinedContext.length > 0 ? { context: { background: ctx.combinedContext } } : {}
     });
+    this.trackLiveTasks(ctx.runId, [task.id]);
     const result = await this.options.tasks.run(task.id);
     if (result.status !== "completed") {
       return {
@@ -3753,6 +3852,24 @@ function registerPipelineCommands(program) {
     }
     await runPipelineAction(def.id, objective ?? previous.objective);
   });
+  pipeline.command("cancel <run-id>").description("Request cancellation of a pipeline run (stops scheduling and cancels running tasks).").action(async (runId) => {
+    const config = loadConfig();
+    const engine = buildPipelineEngine(config);
+    await engine.cancel(runId);
+    console.log(`Cancellation requested for run ${runId}.`);
+    console.log("A run executing in another process stops at its next check point.");
+  });
+  pipeline.command("validate <id>").description("Validate a pipeline definition before running it (\xA79.5).").action(async (id) => {
+    const config = loadConfig();
+    const def = findPipeline(config, id);
+    const engine = buildPipelineEngine(config);
+    engine.validate(def);
+    console.log(`Pipeline "${def.id}" is valid (${def.steps.length} step(s)).`);
+    for (const step of def.steps) {
+      const deps = step.dependsOn?.join(", ") ?? "(previous step)";
+      console.log(`  ${step.id}  kind=${step.kind}  depends_on=${deps}`);
+    }
+  });
   pipeline.command("runs <id>").description("List recorded runs of a pipeline.").action(async (id) => {
     const config = loadConfig();
     const engine = buildPipelineEngine(config);
@@ -3762,7 +3879,8 @@ function registerPipelineCommands(program) {
       return;
     }
     for (const run2 of runs) {
-      console.log(`${run2.id}  ${run2.status.padEnd(10)} ${run2.startedAt ?? "?"}`);
+      const note = isInterrupted(run2) ? "  (interrupted \u2014 process gone before finish)" : "";
+      console.log(`${run2.id}  ${run2.status.padEnd(10)} ${run2.startedAt ?? "?"}${note}`);
     }
   });
   pipeline.command("status <run-id>").description("Show the recorded state of a pipeline run.").action(async (runId) => {
@@ -3780,6 +3898,13 @@ function registerPipelineCommands(program) {
     console.log(`  status:     ${run2.status}`);
     console.log(`  started:    ${run2.startedAt ?? "?"}`);
     if (run2.finishedAt) console.log(`  finished:   ${run2.finishedAt}`);
+    console.log(`  attempt:   ${run2.attempt}`);
+    if (run2.cancellationRequested) {
+      console.log(`  cancellation requested at ${run2.cancellationRequestedAt ?? "?"}`);
+    }
+    if (isInterrupted(run2)) {
+      console.log("  note:       this run looks interrupted (no finishedAt) \u2014 retry with `pipeline retry`");
+    }
     if (run2.resultSummary) console.log(`  result:     ${run2.resultSummary}`);
     for (const stepRun of run2.stepRuns) {
       console.log(`  [${stepRun.stepId}] ${stepRun.status}`);
@@ -3821,6 +3946,9 @@ async function runPipelineAction(id, objective) {
 function registerRunAlias(program) {
   program.command("run <id> [objective]").description("Alias of `omninode pipeline run` \u2014 execute a configured pipeline end to end.").action(async (id, objective) => runPipelineAction(id, objective));
 }
+function isInterrupted(run2) {
+  return run2.status === "running" && run2.finishedAt === void 0;
+}
 function findPipeline(config, id) {
   const def = config.project.pipelines.find((p) => p.id === id);
   if (!def) {