Merge pull request #7050 from nexu-io/backport-6993-to-release/v0.20.0

[backport release/v0.20.0] fix(daemon): carry Vela image safety refusals through to the client

Author: lefarcen

apps/daemon/src/integrations/vela-command.ts

@@ -18,6 +18,41 @@ import {
 } from '../runtimes/launch.js';
 import { getAgentDef } from '../runtimes/registry.js';
 
+/**
+ * A failed Vela command still carries meaning on stdout.
+ *
+ * `vela image gen --json` prints the complete task object — including its
+ * structured `error` block — and only then exits non-zero. Rejecting with the
+ * bare exec error therefore threw away the one thing that distinguishes a
+ * content-safety rejection from a provider outage, leaving every caller with
+ * nothing but "Command failed with exit code 1".
+ *
+ * The stdout is attached to the rejection rather than resolved, so the command
+ * still fails and no caller can mistake a failure for success; readers that
+ * want the structured detail opt in through `velaCommandStdout`.
+ */
+function withCommandStdout(error: unknown, stdout: string): unknown {
+  if (!stdout || typeof error !== 'object' || error === null) return error;
+  try {
+    (error as { stdout?: string }).stdout = stdout;
+  } catch {
+    // A frozen or exotic error object must not turn a command failure into a
+    // different, more confusing failure.
+  }
+  return error;
+}
+
+/**
+ * Read the stdout captured by `withCommandStdout` off a rejected Vela command.
+ * Returns an empty string when the failure carried none (a crash before any
+ * output, or a non-object rejection).
+ */
+export function velaCommandStdout(error: unknown): string {
+  if (typeof error !== 'object' || error === null) return '';
+  const stdout = (error as { stdout?: unknown }).stdout;
+  return typeof stdout === 'string' ? stdout : '';
+}
+
 export interface VelaCommandOptions {
   env?: NodeJS.ProcessEnv;
   configuredEnv?: Record<string, string>;
@@ -276,7 +311,7 @@ export function runVelaCommand(
             // Diagnostics are observational and must never change transport.
           }
         }
-        if (error) settle({ error });
+        if (error) settle({ error: withCommandStdout(error, stdout) });
         else settle({ stdout });
       },
     );

apps/daemon/src/media/tasks.ts

@@ -7,10 +7,26 @@ export type MediaTaskStatus =
   | 'failed'
   | 'interrupted';
 
+/** What a content-safety policy objected to, when the supplier proved it. */
+export type MediaTaskErrorSubject = 'prompt' | 'input_image' | 'output_image';
+
 export interface MediaTaskError {
   message: string;
   status?: number;
   code?: string;
+  /**
+   * Optional hint about what a content-safety policy objected to, forwarded
+   * only when the upstream supplier proved it. Absent means "not proven", not
+   * "not applicable" — a client must then name both the prompt and the
+   * reference images rather than blame one of them.
+   */
+  subject?: MediaTaskErrorSubject;
+  /**
+   * Whether repeating the identical request could plausibly behave
+   * differently. Undefined means the producer did not say; only an explicit
+   * `false` licenses telling a user that retrying is pointless.
+   */
+  retryable?: boolean;
 }
 
 export interface MediaTaskRow {
@@ -309,6 +325,29 @@ function parseArray(json: string | null): string[] {
     : [];
 }
 
+/**
+ * Subjects a content-safety refusal may name. Validated on read as well as on
+ * write: the value crosses a JSON column, so a row written by a newer daemon
+ * (or hand-edited) must not smuggle an unknown subject back into the API
+ * response.
+ */
+const MEDIA_TASK_ERROR_SUBJECTS = ['prompt', 'input_image', 'output_image'] as const;
+
+function isMediaTaskErrorSubject(value: unknown): value is MediaTaskErrorSubject {
+  return (
+    typeof value === 'string'
+    && (MEDIA_TASK_ERROR_SUBJECTS as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * Rebuild a persisted error. Every field the write path stores has to be
+ * reconstructed here or it silently disappears the moment a task is read back
+ * from SQLite -- which is every daemon restart and every cache rehydration,
+ * not an edge case. `subject` and `retryable` were lost that way: a refusal
+ * survived until the process bounced, then reappeared as a bare failure with
+ * no attribution and no retry verdict.
+ */
 function normalizeError(value: unknown): MediaTaskError | null {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
   const obj = value as Record<string, unknown>;
@@ -317,6 +356,11 @@ function normalizeError(value: unknown): MediaTaskError | null {
   const error: MediaTaskError = { message };
   if (typeof obj.status === 'number') error.status = obj.status;
   if (typeof obj.code === 'string') error.code = obj.code;
+  if (isMediaTaskErrorSubject(obj.subject)) error.subject = obj.subject;
+  // Only an explicit boolean survives: absent must stay absent, because
+  // "the producer did not say" and "the producer said retrying is pointless"
+  // are different answers to a client.
+  if (typeof obj.retryable === 'boolean') error.retryable = obj.retryable;
   return error;
 }
 

apps/daemon/src/media/vela.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 
 import {
   runVelaCommand,
+  velaCommandStdout,
   velaWorkspaceCommandOptions,
 } from '../integrations/vela-command.js';
 
@@ -378,10 +379,17 @@ export async function renderVelaImage(
       outputPath,
       '--json',
     ];
-    const stdout = await runCommand(args, {
-      ...velaWorkspaceCommandOptions(input.workspaceId),
-      timeoutMs: VELA_IMAGE_TIMEOUT_MS,
-    });
+    let stdout: string;
+    try {
+      stdout = await runCommand(args, {
+        ...velaWorkspaceCommandOptions(input.workspaceId),
+        timeoutMs: VELA_IMAGE_TIMEOUT_MS,
+      });
+    } catch (error) {
+      // A refused request is a verdict the user can act on, so it must reach
+      // them as one. Everything else keeps its original error untouched.
+      throw velaMediaErrorFromFailure(error, `image ${command}`) ?? error;
+    }
     const asset = parseJsonObject(stdout, `image ${command}`);
     const assetId = nonEmptyString(asset.asset_id);
     const status = nonEmptyString(asset.status);
@@ -412,6 +420,97 @@ export async function renderVelaImage(
   }
 }
 
+/**
+ * The stable, provider-neutral code Vela publishes when a content-safety
+ * policy refused an image request. It is the same string at every layer from
+ * the provider adapter through the API and the CLI, which is what makes it
+ * safe to key product behaviour on.
+ */
+export const VELA_SAFETY_REJECTION_CODE = 'safety_rejection';
+
+/**
+ * Optional, non-authoritative hint about what a safety policy objected to.
+ * Absent whenever the upstream supplier could not prove it — callers must then
+ * fall back to naming both possibilities rather than picking one.
+ */
+export type VelaSafetySubject = 'prompt' | 'input_image' | 'output_image';
+
+const VELA_SAFETY_SUBJECTS: readonly string[] = [
+  'prompt',
+  'input_image',
+  'output_image',
+];
+
+/**
+ * A Vela media failure that arrived with a machine-readable verdict rather
+ * than only a human sentence.
+ *
+ * `code` is carried on the error itself because the media task route copies
+ * `err.code` straight into the persisted task snapshot; that is what lets the
+ * web client render a definite explanation instead of depending on the agent
+ * to repeat one correctly.
+ */
+export class VelaMediaError extends Error {
+  readonly code: string;
+  readonly subject: VelaSafetySubject | undefined;
+  readonly retryable: boolean | undefined;
+
+  constructor(
+    message: string,
+    detail: {
+      code: string;
+      subject?: VelaSafetySubject | undefined;
+      retryable?: boolean | undefined;
+    },
+  ) {
+    super(message);
+    this.name = 'VelaMediaError';
+    this.code = detail.code;
+    this.subject = detail.subject;
+    this.retryable = detail.retryable;
+  }
+}
+
+function safetySubject(value: unknown): VelaSafetySubject | undefined {
+  return typeof value === 'string' && VELA_SAFETY_SUBJECTS.includes(value)
+    ? (value as VelaSafetySubject)
+    : undefined;
+}
+
+/**
+ * Rebuild a structured failure from a rejected `vela image --json` run.
+ *
+ * Returns undefined for every failure that carried no task JSON — a CLI
+ * validation error, a crash, a timeout — so those keep their existing generic
+ * handling. An unrecognised or absent `code` is deliberately NOT promoted to a
+ * safety rejection: mislabelling an outage as a policy refusal would send a
+ * user off to rewrite a prompt that was never the problem.
+ */
+export function velaMediaErrorFromFailure(
+  error: unknown,
+  label: string,
+): VelaMediaError | undefined {
+  const stdout = velaCommandStdout(error).trim();
+  if (!stdout) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(parsed) || !isRecord(parsed.error)) return undefined;
+  const code = nonEmptyString(parsed.error.code);
+  if (!code) return undefined;
+  const message = nonEmptyString(parsed.error.message);
+  const retryable =
+    typeof parsed.error.retryable === 'boolean' ? parsed.error.retryable : undefined;
+  return new VelaMediaError(message ?? `Vela ${label} failed with ${code}`, {
+    code,
+    subject: safetySubject(parsed.error.subject),
+    retryable,
+  });
+}
+
 export async function renderVelaVideo(
   input: VelaVideoRenderInput,
   runCommand: VelaCommandRunner = runVelaCommand,

apps/daemon/src/prompts/media-contract.ts

@@ -50,13 +50,24 @@ localized sentence and nothing else:
 
 - Success: say the localized equivalent of "Image generated". For Simplified
   Chinese, reply exactly \`图片已生成\`.
-- Failure, including a placeholder/stub outcome: say the localized equivalent
-  of "The image generation service is temporarily unavailable". For Simplified
-  Chinese, reply exactly \`图片生成服务暂时不可用\`.
-
-Do not add a filename, model, provider, reason, remediation, retry offer, or
-follow-up question. Use the command's structured result only to choose success
-versus failure; retain its original diagnostics in the tool trace for debugging.`;
+- Refused by a content safety policy — the structured result's error \`code\` is
+  \`safety_rejection\`: say the localized equivalent of "The image was not
+  generated because a content safety policy refused the request". For
+  Simplified Chinese, reply exactly \`图片未生成：内容安全策略拒绝了该请求\`.
+- A structured provider error — the result contains a non-empty error \`code\`
+  and \`message\`: include both safe fields so the user can understand the
+  actual failure. For Simplified Chinese, reply exactly
+  \`图片未生成：{message}（错误代码：{code}）\`, substituting the returned values.
+- Any other failure, including a placeholder/stub outcome: say the localized
+  equivalent of "The image generation service is temporarily unavailable". For
+  Simplified Chinese, reply exactly \`图片生成服务暂时不可用\`.
+
+A provider verdict is not automatically an outage. Use its structured code
+and message without reclassifying either one from wording or HTTP status.
+
+Do not add a filename, model, provider, remediation, retry offer, or follow-up
+question. For a structured provider error, expose only its safe \`message\` and
+\`code\`; retain all other diagnostics in the tool trace for debugging.`;
 
 export function renderMediaGenerationContract(
   mediaExecution?: MediaExecutionPolicy | undefined,

apps/daemon/src/routes/media.ts

@@ -8,6 +8,7 @@ import type { AnalyticsContext } from '../analytics.js';
 import { defaultMediaExecutionPolicy, mediaPolicyDenial } from '../media/policy.js';
 import { formatMediaTaskDiagnostic } from '../media/diagnostics.js';
 import { findMediaModel } from '../media/models.js';
+import type { MediaTaskError } from '../media/tasks.js';
 import type { ImageGenerationRequestSummary } from '../media/image-generation-retry.js';
 import type { RouteDeps } from '../server-context.js';
 import type {
@@ -96,6 +97,32 @@ export function resolveLegacyMediaRouteGrant(input: {
   return { ok: true, grant: input.grant };
 }
 
+
+/**
+ * Build the persisted failure record for a media task.
+ *
+ * A media failure is the only thing the client has left to explain itself
+ * with, so anything the producer proved must survive into the snapshot: the
+ * stable `code` the web client keys its copy on, the optional `subject`
+ * naming what a safety policy objected to, and `retryable` so the UI can stop
+ * inviting a retry that cannot succeed. Absent fields stay absent rather than
+ * being defaulted — `retryable: false` invented here would tell a user a
+ * transient outage is permanent.
+ */
+function mediaTaskErrorFromFailure(err: any): MediaTaskError {
+  const subject = err?.subject;
+  const retryable = err?.retryable;
+  return {
+    message: String(err && err.message ? err.message : err),
+    status: typeof err?.status === 'number' ? err.status : 400,
+    code: err?.code,
+    ...(subject === 'prompt' || subject === 'input_image' || subject === 'output_image'
+      ? { subject }
+      : {}),
+    ...(typeof retryable === 'boolean' ? { retryable } : {}),
+  };
+}
+
 export function registerMediaRoutes(app: Express, ctx: RegisterMediaRoutesDeps) {
   const { db, design } = ctx;
   const { sendApiError, requireLocalDaemonRequest, isLocalSameOrigin, resolvedPortRef } = ctx.http;
@@ -295,11 +322,7 @@ export function registerMediaRoutes(app: Express, ctx: RegisterMediaRoutesDeps)
         })
         .catch((err: any) => {
           task.status = 'failed';
-          task.error = {
-            message: String(err && err.message ? err.message : err),
-            status: typeof err?.status === 'number' ? err.status : 400,
-            code: err?.code,
-          };
+          task.error = mediaTaskErrorFromFailure(err);
           task.endedAt = Date.now();
           persistMediaTask(task);
           if (analyticsContext && providerRequestSummary) {
@@ -335,11 +358,7 @@ export function registerMediaRoutes(app: Express, ctx: RegisterMediaRoutesDeps)
     } catch (err: any) {
       if (task) {
         task.status = 'failed';
-        task.error = {
-          message: String(err && err.message ? err.message : err),
-          status: typeof err?.status === 'number' ? err.status : 400,
-          code: err?.code,
-        };
+        task.error = mediaTaskErrorFromFailure(err);
         task.endedAt = Date.now();
         persistMediaTask(task);
         notifyTaskWaiters(task);