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

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.6";
 
 // src/errors/index.ts
 var OmniNodeError = class extends Error {
@@ -363,35 +363,32 @@ function authHeaders(config, env = process.env) {
 }
 
 // src/providers/http.ts
+var HttpResponseError = class extends Error {
+  constructor(message, status, cause) {
+    super(message, { cause });
+    this.status = status;
+    this.name = "HttpResponseError";
+  }
+  status;
+};
 var DEFAULT_TIMEOUT_MS = 3e4;
 async function requestJson(url, options = {}) {
   const { method = "GET", headers = {}, body, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
-  let response;
-  try {
-    response = await fetch(url, {
-      method,
-      headers: {
-        accept: "application/json",
-        ...body !== void 0 ? { "content-type": "application/json" } : {},
-        ...headers
-      },
-      ...body !== void 0 ? { body: JSON.stringify(body) } : {},
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-  } catch (error) {
-    const reason = error instanceof Error && error.name === "TimeoutError" ? `timed out after ${timeoutMs}ms` : error instanceof Error ? error.message : String(error);
-    throw new ProviderError("PROVIDER_UNAVAILABLE", `Request to ${url} failed: ${reason}.`, {
-      cause: error
-    });
-  }
+  const response = await fetch(url, {
+    method,
+    headers: {
+      accept: "application/json",
+      ...body !== void 0 ? { "content-type": "application/json" } : {},
+      ...headers
+    },
+    ...body !== void 0 ? { body: JSON.stringify(body) } : {},
+    signal: AbortSignal.timeout(timeoutMs)
+  });
   let parsed;
   try {
     parsed = await response.json();
   } catch (error) {
-    throw new ProviderError("PROVIDER_UNAVAILABLE", `Response from ${url} was not valid JSON.`, {
-      cause: error,
-      details: { status: response.status }
-    });
+    throw new HttpResponseError(`Response from ${url} was not valid JSON.`, response.status, error);
   }
   return { status: response.status, body: parsed };
 }
@@ -452,23 +449,151 @@ var Logger = class _Logger {
 };
 var logger = new Logger();
 
+// src/providers/errors.ts
+function kindToCode(kind) {
+  switch (kind) {
+    case "AUTHENTICATION_ERROR":
+      return "PROVIDER_AUTH_FAILED";
+    case "MODEL_NOT_FOUND":
+      return "MODEL_NOT_FOUND";
+    default:
+      return "PROVIDER_UNAVAILABLE";
+  }
+}
+function isRetryable(kind) {
+  return kind === "RATE_LIMIT_ERROR" || kind === "SERVER_ERROR" || kind === "NETWORK_ERROR";
+}
+function kindFromStatus(status) {
+  if (status === 401 || status === 403) return "AUTHENTICATION_ERROR";
+  if (status === 429) return "RATE_LIMIT_ERROR";
+  if (status === 404) return "MODEL_NOT_FOUND";
+  if (status === 408 || status === 504) return "TIMEOUT";
+  if (status >= 500) return "SERVER_ERROR";
+  if (status >= 400) return "INVALID_REQUEST";
+  return "UNKNOWN_ERROR";
+}
+function extractMessage(body) {
+  if (body === null || typeof body !== "object") return void 0;
+  const root = body;
+  const error = root.error ?? root;
+  const message = error.message ?? error.detail ?? root.message;
+  return typeof message === "string" ? message : void 0;
+}
+function parseRetryAfter(value, now = Date.now()) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? void 0 : Math.max(0, date - now);
+}
+function isTimeoutError(error) {
+  return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError") || typeof error?.code === "string" && error.code === "ABORT_ERR";
+}
+function fallbackMessage(kind, context, status) {
+  const { provider, operation } = context;
+  switch (kind) {
+    case "AUTHENTICATION_ERROR":
+      return `Authentication with provider "${provider}" failed (HTTP ${status}). Check that the referenced API key is set and valid.`;
+    case "RATE_LIMIT_ERROR":
+      return `Provider "${provider}" rate-limited ${operation} (HTTP ${status}). Retry later.`;
+    case "MODEL_NOT_FOUND":
+      return `Provider "${provider}" does not expose the requested model (HTTP ${status}).`;
+    case "TIMEOUT":
+      return `Provider "${provider}" timed out during ${operation} (HTTP ${status}).`;
+    case "SERVER_ERROR":
+      return `Provider "${provider}" returned a server error during ${operation} (HTTP ${status}).`;
+    case "INVALID_REQUEST":
+      return `Provider "${provider}" rejected ${operation} as invalid (HTTP ${status}).`;
+    default:
+      return `Provider "${provider}" failed during ${operation} (HTTP ${status}).`;
+  }
+}
+function providerHttpError(context) {
+  const status = context.status ?? 0;
+  const kind = kindFromStatus(status);
+  const detail = extractMessage(context.body);
+  const retryAfterMs = context.retryAfterMs ?? parseRetryAfter(void 0);
+  return new ProviderError(
+    context.code ?? kindToCode(kind),
+    detail ?? fallbackMessage(kind, context, status),
+    {
+      cause: context.cause,
+      details: {
+        kind,
+        provider: context.provider,
+        operation: context.operation,
+        status,
+        retryable: isRetryable(kind),
+        ...retryAfterMs !== void 0 ? { retryAfterMs } : {},
+        ...detail ? { providerMessage: detail } : {}
+      }
+    }
+  );
+}
+function providerTransportError(context) {
+  const cause = context.cause;
+  const kind = isTimeoutError(cause) ? "TIMEOUT" : cause instanceof SyntaxError || cause?.name === "HttpResponseError" ? "UNKNOWN_ERROR" : "NETWORK_ERROR";
+  const message = context.cause instanceof Error ? context.cause.message : String(context.cause);
+  return new ProviderError("PROVIDER_UNAVAILABLE", `Provider request failed: ${message}`, {
+    cause: context.cause,
+    details: {
+      kind,
+      provider: context.provider,
+      operation: context.operation,
+      retryable: isRetryable(kind)
+    }
+  });
+}
+
 // src/providers/openai-compatible/index.ts
 var OpenAICompatibleProvider = class {
   config;
+  providerId;
+  authentication;
   log;
-  constructor(config, log = logger) {
+  /** Discovered models, so getModel() answers without another round-trip. */
+  discovered;
+  env;
+  constructor(config, log = logger, env = process.env) {
     this.config = { ...config, baseUrl: normalizeBaseUrl(config.baseUrl) };
+    this.env = env;
+    this.providerId = config.providerId ?? config.name;
+    this.authentication = {
+      method: config.apiKeyEnvVar ? "bearer" : "none",
+      ...config.apiKeyEnvVar ? { envVar: config.apiKeyEnvVar } : {},
+      configured: config.apiKeyEnvVar ? Boolean(env[config.apiKeyEnvVar]) : true
+    };
     this.log = log.child({ provider: config.name });
   }
+  /** Authenticate + discover (roadmap §10, Model Discovery). */
+  async connect() {
+    authHeaders(this.config, this.env);
+    const models = await this.listModels();
+    this.discovered = models;
+    return models;
+  }
+  async getModel(modelId) {
+    const models = this.discovered ?? await this.connect();
+    return models.find((m) => m.id === modelId);
+  }
   async listModels() {
-    const { status, body } = await requestJson(`${this.config.baseUrl}/models`, {
-      headers: authHeaders(this.config)
-    });
-    if (status === 401 || status === 403) {
-      throw authFailed(this.config, status);
+    let response;
+    try {
+      response = await requestJson(`${this.config.baseUrl}/models`, {
+        headers: authHeaders(this.config, this.env)
+      });
+    } catch (error) {
+      if (error instanceof ProviderError) throw error;
+      throw providerTransportError({ provider: this.config.name, operation: "listModels", cause: error });
     }
+    const { status, body } = response;
     if (status !== 200) {
-      throw unavailable(this.config, `Model discovery returned HTTP ${status}.`, status);
+      throw providerHttpError({
+        provider: this.config.name,
+        operation: "listModels",
+        status,
+        body
+      });
     }
     const entries = extractModelEntries(body, this.config);
     const models = [];
@@ -478,22 +603,40 @@ var OpenAICompatibleProvider = class {
         skipped += 1;
         continue;
       }
-      models.push({
-        provider: this.config.name,
-        id: entry2.id,
-        displayName: entry2.id,
-        status: "available",
-        metadata: {
-          ...typeof entry2.owned_by === "string" ? { ownedBy: entry2.owned_by } : {},
-          ...typeof entry2.created === "number" ? { createdAt: entry2.created } : {}
-        }
-      });
+      models.push(this.toModelInfo(entry2));
     }
     if (skipped > 0) {
       this.log.warn(`Skipped ${skipped} model entr(y/ies) without a valid id.`);
     }
     return models;
   }
+  /** Maps a raw model entry onto the normalized metadata shape (§10). */
+  toModelInfo(entry2) {
+    const parameters = Array.isArray(entry2.supported_parameters) ? entry2.supported_parameters.filter((p) => typeof p === "string") : void 0;
+    const contextWindow = typeof entry2.context_length === "number" ? entry2.context_length : typeof entry2.context_window === "number" ? entry2.context_window : void 0;
+    const inputTypes = normalizeModalities(entry2.input_modalities);
+    const outputTypes = normalizeModalities(entry2.output_modalities);
+    return {
+      provider: this.config.name,
+      id: entry2.id,
+      displayName: entry2.id,
+      ...typeof entry2.name === "string" ? { name: entry2.name } : {},
+      status: "available",
+      ...contextWindow !== void 0 ? { contextWindow } : {},
+      ...inputTypes !== void 0 ? { inputTypes } : {},
+      ...outputTypes !== void 0 ? { outputTypes } : {},
+      ...parameters !== void 0 ? {
+        supportsTools: parameters.includes("tools") || parameters.includes("tool_choice"),
+        supportsStructuredOutput: parameters.includes("response_format"),
+        supportsStreaming: parameters.includes("stream")
+      } : {},
+      metadata: {
+        ...typeof entry2.owned_by === "string" ? { ownedBy: entry2.owned_by } : {},
+        ...typeof entry2.created === "number" ? { createdAt: entry2.created } : {},
+        ...parameters !== void 0 ? { supportedParameters: parameters } : {}
+      }
+    };
+  }
   async healthCheck() {
     const lastCheckedAt = (/* @__PURE__ */ new Date()).toISOString();
     try {
@@ -523,27 +666,34 @@ var OpenAICompatibleProvider = class {
     }
   }
   async chat(request) {
-    const { status, body } = await requestJson(`${this.config.baseUrl}/chat/completions`, {
-      method: "POST",
-      headers: authHeaders(this.config),
-      body: {
-        model: request.model,
-        messages: request.messages,
-        ...request.temperature !== void 0 ? { temperature: request.temperature } : {},
-        ...request.maxTokens !== void 0 ? { max_tokens: request.maxTokens } : {},
-        ...request.stop !== void 0 ? { stop: request.stop } : {}
-      }
-    });
-    if (status === 401 || status === 403) throw authFailed(this.config, status);
-    if (status === 404) {
-      throw new ProviderError(
-        "MODEL_NOT_FOUND",
-        `Model "${request.model}" or the chat endpoint was not found on provider "${this.config.name}" (HTTP 404).`,
-        { details: { status } }
-      );
+    let response;
+    try {
+      response = await requestJson(`${this.config.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: authHeaders(this.config, this.env),
+        body: {
+          model: request.model,
+          messages: request.messages,
+          ...request.temperature !== void 0 ? { temperature: request.temperature } : {},
+          ...request.maxTokens !== void 0 ? { max_tokens: request.maxTokens } : {},
+          ...request.stop !== void 0 ? { stop: request.stop } : {}
+        }
+      });
+    } catch (error) {
+      if (error instanceof ProviderError) throw error;
+      throw providerTransportError({ provider: this.config.name, operation: "chat", cause: error });
     }
+    const { status, body } = response;
     if (status !== 200) {
-      throw unavailable(this.config, `Chat completion returned HTTP ${status}.`, status);
+      throw providerHttpError({
+        provider: this.config.name,
+        operation: "chat",
+        status,
+        body,
+        ...status === 404 ? {
+          code: "MODEL_NOT_FOUND"
+        } : {}
+      });
     }
     const payload = body;
     const choices = Array.isArray(payload.choices) ? payload.choices : [];
@@ -565,6 +715,13 @@ var OpenAICompatibleProvider = class {
     };
   }
 };
+function normalizeModalities(value) {
+  const list = Array.isArray(value) ? value : typeof value === "string" ? [value] : void 0;
+  if (!list) return void 0;
+  const allowed = /* @__PURE__ */ new Set(["text", "image", "audio", "video", "embedding"]);
+  const modalities = list.filter((m) => typeof m === "string" && allowed.has(m));
+  return modalities.length > 0 ? modalities : void 0;
+}
 function normalizeBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
@@ -579,14 +736,6 @@ function extractModelEntries(body, config) {
     { details: { endpoint: "models" } }
   );
 }
-function authFailed(config, status) {
-  const envHint = config.apiKeyEnvVar ? ` Check that $${config.apiKeyEnvVar} is set and valid.` : " The provider requires authentication; configure api_key_env_var for it.";
-  return new ProviderError(
-    "PROVIDER_AUTH_FAILED",
-    `Authentication with provider "${config.name}" failed (HTTP ${status}).${envHint}`,
-    { details: { status } }
-  );
-}
 function unavailable(config, message, status) {
   return new ProviderError("PROVIDER_UNAVAILABLE", `Provider "${config.name}": ${message}`, {
     details: { status }
@@ -603,7 +752,7 @@ var OmniHilbrasProvider = class extends OpenAICompatibleProvider {
    * Run the full connect flow. Throws on authentication or transport failure
    * (use healthCheck() for a non-throwing probe).
    */
-  async connect(registry) {
+  async connectAndRegister(registry) {
     const apiKey = resolveApiKey(this.config);
     const discovered = await this.listModels();
     const seen = /* @__PURE__ */ new Set();
@@ -827,7 +976,7 @@ async function testProvider(name, options = {}) {
   if (options.connect && provider instanceof OmniHilbrasProvider) {
     const registry = new ModelRegistry();
     try {
-      const result = await provider.connect(registry);
+      const result = await provider.connectAndRegister(registry);
       printProviderStatus(result.status);
       console.log(`  registered: ${result.registered}`);
     } catch (error) {
@@ -1634,7 +1783,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 +2217,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 +3347,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 +3463,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 +3512,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 +3544,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 +3562,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 +3573,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 +3606,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 +3628,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 +3668,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 +3710,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 +3735,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 +3750,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 +4001,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 +4028,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 +4047,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 +4095,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) {