Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

6.9 KB
Raw Blame
/**
 * runStepSummary (issue B20)
 * --------------------------
 *
 * Derives a single plain-language line describing what a workflow step did,
 * for laypeople who don't care about `costUsd`/`labelIds`/`markdownFormatted`
 * or which node kind ran — they want "✅ Sent your daily email summary" or
 * "❌ Couldn't send email: recipient address invalid", not raw Composio JSON.
 *
 * Deliberately generic — no tool-name-specific string matching (no "gmail",
 * no "slack"). It only reasons about the *shape* of the normalized output:
 *
 *   - `FlowRunStep.status` ("success"/"error", when the observer recorded
 *     one — see `services/api/flowsApi.ts`) is the primary success/failure
 *     signal.
 *   - A node can also report engine-level success while the underlying tool
 *     call itself failed — the common Composio tool-call envelope shape is
 *     `{ data, successful, error, costUsd, markdownFormatted }`
 *     (`crates/openhuman-core/src/flows/tinyflows/caps.rs`) — `successful: false` (with or
 *     without a `status`) is treated as a failure too.
 *   - Known "the tool already told us in plain English" fields (`summary`,
 *     `message`, `text`) are surfaced verbatim when present — this is how a
 *     node like the daily-email-summary agent's `{ summary: "..." }` payload
 *     becomes the primary line instead of being buried in raw JSON.
 *   - Failing that, item/array counts ("Fetched 20 item(s)") give a generic
 *     but still useful line for any tool that returns a list.
 *
 * Internal `flow:`/`run:` ids are never surfaced here — this module only ever
 * sees a step's already-normalized output items, never the `FlowRun` record.
 */
import createDebug from 'debug';

import { truncateText } from '../../utils/truncateText';
import { type FlowRunItem, isPlainObject } from './runItems';

const log = createDebug('app:flows:step-summary');

type StepOutcome = 'success' | 'error' | 'neutral';

interface StepSummary {
  outcome: StepOutcome;
  /** Plain-language, already-localized one-line summary (translation-ready inputs applied). */
  text: string;
}

/** Cap the summary line so one verbose tool response can't blow out the layout. */
const MAX_SUMMARY_CHARS = 180;

function truncate(text: string): string {
  return truncateText(text, MAX_SUMMARY_CHARS, { trim: true });
}

/** Read a string field off a plain object, ignoring blank/non-string values. */
function stringField(obj: Record<string, unknown>, key: string): string | null {
  const value = obj[key];
  return typeof value === 'string' && value.trim() ? value : null;
}

/**
 * Extract a human-readable error reason from a payload: a bare string error,
 * or the common `{ error: "..." }` / `{ error: { message: "..." } }` shapes.
 */
function extractErrorMessage(payload: unknown): string | null {
  if (typeof payload === 'string' && payload.trim()) return payload;
  if (!isPlainObject(payload)) return null;
  const err = payload.error;
  if (typeof err === 'string' && err.trim()) return err;
  if (isPlainObject(err)) {
    const message = stringField(err, 'message');
    if (message) return message;
  }
  return stringField(payload, 'error_message');
}

/** Composio-style tool envelope: `successful: false` marks a failed tool call. */
function isMarkedUnsuccessful(payload: unknown): boolean {
  return isPlainObject(payload) && payload.successful === false;
}

/** The single payload this step's items represent, for summarization purposes. */
function primaryPayload(items: FlowRunItem[]): unknown {
  if (items.length === 0) return undefined;
  if (items.length === 1) return items[0].json;
  return items.map(item => item.json);
}

/** First array found at the payload's top level or under a `data` field, if any. */
function arrayLength(payload: unknown): number | null {
  if (Array.isArray(payload)) return payload.length;
  if (isPlainObject(payload) && Array.isArray(payload.data)) return payload.data.length;
  return null;
}

/**
 * Summarize one step's outcome + output into a single plain-language line.
 * `t` is passed in (rather than calling `useT()` here) so this stays a plain,
 * easily-unit-tested function — callers are React components that already
 * hold a `t` from `useT()`.
 */
export function summarizeStep(
  step: { status?: 'success' | 'error' },
  items: FlowRunItem[],
  t: (key: string) => string
): StepSummary {
  const payload = primaryPayload(items);
  // Failure is only ever inferred from an explicit step status or a *known*
  // failure envelope (Composio-style `successful: false`) — never from a bare
  // top-level `error`/`error_message` field on a status-less payload.
  // Reconstructed steps (e.g. triggers) can omit `status` entirely while
  // still carrying arbitrary user payloads, and a successful webhook/trigger
  // payload that happens to include an `error` field must not render as a
  // failure.
  const errorMessage = extractErrorMessage(payload);
  const unsuccessful = isMarkedUnsuccessful(payload);
  const failed = step.status === 'error' || unsuccessful;

  // Diagnostics: classification inputs only — status presence/value, item
  // count, whether the `successful: false` marker was recognized, and whether
  // an error reason was present. Never the payload contents or error text.
  log(
    'classify: status=%s items=%d successfulFalse=%s hasErrorReason=%s failed=%s',
    step.status ?? 'absent',
    items.length,
    unsuccessful,
    errorMessage !== null,
    failed
  );
  // Tag the selected outcome branch (metadata only) on the way out.
  const decide = (branch: string, summary: StepSummary): StepSummary => {
    log('branch=%s outcome=%s', branch, summary.outcome);
    return summary;
  };

  if (failed) {
    const reason = errorMessage ?? t('flowRuns.inspector.summary.unknownError');
    return decide('failed', {
      outcome: 'error',
      text: truncate(`${t('flowRuns.inspector.summary.failedPrefix')} ${reason}`),
    });
  }

  if (isPlainObject(payload)) {
    const summary = stringField(payload, 'summary') ?? stringField(payload, 'message');
    if (summary) return decide('summary-field', { outcome: 'success', text: truncate(summary) });
  }

  const count = arrayLength(payload);
  if (count !== null) {
    return decide('items-count', {
      outcome: 'success',
      text: truncate(
        t('flowRuns.inspector.summary.itemsFetched').replace('{count}', String(count))
      ),
    });
  }

  if (typeof payload === 'string' && payload.trim()) {
    return decide('string-payload', { outcome: 'success', text: truncate(payload) });
  }
  if (typeof payload === 'number' || typeof payload === 'boolean') {
    return decide('scalar-payload', { outcome: 'success', text: truncate(String(payload)) });
  }

  if (items.length === 0) {
    return decide('no-output', {
      outcome: 'neutral',
      text: t('flowRuns.inspector.summary.noOutput'),
    });
  }

  return decide('completed', {
    outcome: 'success',
    text: t('flowRuns.inspector.summary.completed'),
  });
}