Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
34.2 KB
Raw Blame
import type { Attachment, ToolOutput } from '../types'
import { WorkflowTool } from './workflowBaseTool'
import {
  nonUniqueEffectiveTargetResponse,
  requestEffectiveWorkflowList,
  resolveEffectiveWorkflowTarget,
  shouldResolveEffectiveWorkflowTargets,
} from './workflowEffectiveTargets'
import {
  WORKFLOW_RECIPE_NAMESPACE,
  type WorkflowCallerContext,
  getString,
  requireWorkflowRef,
  workflowTargetSchema,
} from './workflowShared'

const DEFAULT_WORKFLOW_RESULT_ARTIFACT_POLL_ATTEMPTS = 180
const DEFAULT_WORKFLOW_RESULT_ARTIFACT_POLL_INTERVAL_MS = 1_000
const DEFAULT_WORKFLOW_RESULT_ATTACHMENT_MAX_BYTES = 50 * 1024 * 1024
const WORKFLOW_RESULT_BINARY_PREVIEW_MESSAGE = 'Artifact is available for download.'
const WORKFLOW_RESULT_FILE_MIME_BY_EXT = new Map([
  ['json', 'application/json'],
  ['txt', 'text/plain'],
  ['md', 'text/markdown'],
  ['csv', 'text/csv'],
  ['pdf', 'application/pdf'],
  ['docx', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
  ['xlsx', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
])

function workflowResultAttachmentMaxBytes(getEnv: (key: string) => string | undefined): number {
  const parsed = Number(getEnv('CLERUM_ATTACHMENT_MAX_BYTES') || '')
  return Number.isSafeInteger(parsed) && parsed > 0
    ? parsed
    : DEFAULT_WORKFLOW_RESULT_ATTACHMENT_MAX_BYTES
}

function positiveIntegerEnv(
  getEnv: (key: string) => string | undefined,
  key: string,
  fallback: number
): number {
  const parsed = Number(getEnv(key) || '')
  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
}

function workflowResultArtifactPollAttempts(getEnv: (key: string) => string | undefined): number {
  return positiveIntegerEnv(
    getEnv,
    'CLERUM_WORKFLOW_RESULT_ARTIFACT_POLL_ATTEMPTS',
    DEFAULT_WORKFLOW_RESULT_ARTIFACT_POLL_ATTEMPTS
  )
}

function workflowResultArtifactPollIntervalMs(getEnv: (key: string) => string | undefined): number {
  return positiveIntegerEnv(
    getEnv,
    'CLERUM_WORKFLOW_RESULT_ARTIFACT_POLL_INTERVAL_MS',
    DEFAULT_WORKFLOW_RESULT_ARTIFACT_POLL_INTERVAL_MS
  )
}

function isRetryableWorkflowResultArtifactListError(error: unknown): boolean {
  if (!(error instanceof Error)) return false
  return (
    /Workflow broker request failed \((404|410|502|503|504)\)/.test(error.message) ||
    /\b(fetch failed|timeout|aborted)\b/i.test(error.message)
  )
}

function safeAttachmentFilename(raw: string): string {
  const trimmed = raw.trim().replace(/\\/g, '/').split('/').pop() || 'workflow-artifact'
  const cleaned = trimmed.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 160)
  return cleaned && cleaned !== '.' && cleaned !== '..' ? cleaned : 'workflow-artifact'
}

function filenameFromDispositionOrArtifact(raw: unknown, artifactName: string): string {
  if (typeof raw !== 'string') return safeAttachmentFilename(artifactName)
  const match = raw.match(/filename="?([^";\r\n]+)"?/i)
  return safeAttachmentFilename(match?.[1] || raw || artifactName)
}

function extensionOf(filename: string): string {
  const idx = filename.lastIndexOf('.')
  return idx >= 0 ? filename.slice(idx + 1).toLowerCase() : ''
}

function allowedWorkflowResultMime(filename: string, contentType: string): string | null {
  const expected = WORKFLOW_RESULT_FILE_MIME_BY_EXT.get(extensionOf(filename))
  if (!expected) return null
  const normalized = contentType.split(';', 1)[0]?.trim().toLowerCase() || ''
  if (normalized === expected) return expected
  if (expected === 'application/json' && normalized === 'text/json') return expected
  if (!normalized || normalized === 'application/octet-stream') return expected
  return null
}

type WorkflowResultArtifactDownload = {
  contentResult: unknown
  attachment: Attachment | null
}

function contentResultFromDownloadBytes(params: {
  artifactName: string
  contentType: string
  body: Buffer
}): unknown {
  const { artifactName, contentType, body } = params
  const sizeBytes = body.byteLength
  if (sizeBytes > 256 * 1024) {
    return {
      artifactName,
      contentType,
      sizeBytes,
      truncated: true,
      message: 'Artifact is too large to load into agent context. Use the downloaded file.',
    }
  }
  const text = body.toString('utf8')
  if (allowedWorkflowResultMime(artifactName, contentType) === 'application/json') {
    try {
      return {
        artifactName,
        contentType,
        sizeBytes,
        content: JSON.parse(text) as unknown,
      }
    } catch {
      return { artifactName, contentType, sizeBytes, contentText: text }
    }
  }
  if (/^text\//i.test(contentType) || /\.(md|txt|csv)$/i.test(artifactName)) {
    return { artifactName, contentType, sizeBytes, contentText: text }
  }
  return {
    artifactName,
    contentType,
    sizeBytes,
    message: WORKFLOW_RESULT_BINARY_PREVIEW_MESSAGE,
  }
}

function contentResultWithAttachmentDelivery(
  contentResult: unknown,
  attachment: Attachment | null
): unknown {
  if (
    !attachment ||
    !contentResult ||
    typeof contentResult !== 'object' ||
    Array.isArray(contentResult)
  ) {
    return contentResult
  }
  const result = contentResult as Record<string, unknown>
  if (result.message !== WORKFLOW_RESULT_BINARY_PREVIEW_MESSAGE) return contentResult
  return {
    ...result,
    message: `Artifact is available for download and attached as ${attachment.filename}.`,
    previewAvailable: false,
    downloadableAttachment: {
      filename: attachment.filename,
      mimeType: attachment.mimeType,
      sizeBytes: attachment.sizeBytes,
      delivery: 'response_attachment',
    },
  }
}

async function workflowResultArtifactDownload(params: {
  client: {
    download(
      path: string,
      options: { maxBytes: number }
    ): Promise<{
      body: Buffer
      headers: Record<string, string>
    }>
  }
  downloadPath: string
  artifactName: string
  getEnv: (key: string) => string | undefined
}): Promise<WorkflowResultArtifactDownload> {
  const maxBytes = workflowResultAttachmentMaxBytes(params.getEnv)
  const downloaded = await params.client.download(params.downloadPath, { maxBytes })
  const sizeBytes = downloaded.body.byteLength
  const contentType = downloaded.headers['content-type'] || ''
  const filename = filenameFromDispositionOrArtifact(
    downloaded.headers['content-disposition'],
    params.artifactName
  )
  const contentResult = contentResultFromDownloadBytes({
    artifactName: params.artifactName,
    contentType,
    body: downloaded.body,
  })
  const mimeType = allowedWorkflowResultMime(filename, contentType)
  let attachment: Attachment | null = null
  if (!mimeType || sizeBytes <= 0) {
    console.warn(
      `[WorkflowResult] Skipping artifact attachment: mimeAllowed=${Boolean(mimeType)}, ` +
        `sizeBytes=${sizeBytes}, artifact=${params.artifactName}`
    )
  } else {
    if (sizeBytes > maxBytes) {
      console.warn(
        `[WorkflowResult] Skipping oversized artifact attachment: sizeBytes=${sizeBytes}, maxBytes=${maxBytes}, artifact=${params.artifactName}`
      )
    } else {
      attachment = {
        id: `workflow-result-${filename}`,
        kind: 'file',
        mimeType,
        encoding: 'base64',
        dataBase64: downloaded.body.toString(('base' + '64') as BufferEncoding),
        filename,
        caption: `Workflow artifact: ${filename} (${sizeBytes} bytes)`,
        sourceTool: 'workflow_result',
        lane: 'workflow_result',
        artifactName: params.artifactName,
        sizeBytes,
      }
    }
  }
  return {
    contentResult: contentResultWithAttachmentDelivery(contentResult, attachment),
    attachment,
  }
}
function appendApprovalTargetQuery(path: string, params: Record<string, unknown>): string {
  const query = new URLSearchParams()
  const targetUserId = getString(params, 'targetUserId')
  const targetTeamId = getString(params, 'targetTeamId')
  const workflowConversationId = getString(params, 'workflowConversationId')
  if (targetUserId) query.set('targetUserId', targetUserId)
  if (targetTeamId) query.set('targetTeamId', targetTeamId)
  if (workflowConversationId) query.set('workflowConversationId', workflowConversationId)
  const encoded = query.toString()
  return encoded ? `${path}?${encoded}` : path
}

function approvalTargetParams(
  params: Record<string, unknown>,
  context: WorkflowCallerContext | null
): Record<string, unknown> {
  if (!context?.targetUserId && !context?.targetTeamId) return params
  const targetUserId = getString(params, 'targetUserId')
  const targetTeamId = getString(params, 'targetTeamId')
  if (targetUserId) {
    throw new Error('workflow target user is derived from the authenticated conversation')
  }
  if (targetTeamId) {
    throw new Error('workflow target team is derived from the authenticated conversation')
  }
  return context.targetUserId
    ? { targetUserId: context.targetUserId }
    : { targetTeamId: context.targetTeamId }
}

function rejectModelSuppliedApprovalTarget(params: Record<string, unknown>): void {
  if (getString(params, 'targetUserId')) {
    throw new Error('workflow target user is derived from the authenticated conversation')
  }
  if (getString(params, 'targetTeamId')) {
    throw new Error('workflow target team is derived from the authenticated conversation')
  }
}

function approvalTargetParamSet(
  params: Record<string, unknown>,
  context: WorkflowCallerContext | null
): Record<string, unknown>[] {
  const resolved = approvalTargetParams(params, context)
  if (!context?.targetUserId || !context.targetTeamId) return [resolved]
  return [{ targetUserId: context.targetUserId }, { targetTeamId: context.targetTeamId }]
}

function attachWorkflowConversation(
  targets: Record<string, unknown>[],
  context: WorkflowCallerContext | null
): Record<string, unknown>[] {
  const conversationId = context?.conversationId?.trim()
  if (!conversationId) return targets
  return targets.map(target => ({ ...target, workflowConversationId: conversationId }))
}

function isApprovalTargetMiss(error: unknown): boolean {
  if (!(error instanceof Error)) return false
  return /\((403|404)\)/.test(error.message)
}

async function requestWithApprovalTargetFallback(
  targets: Record<string, unknown>[],
  requestForTarget: (target: Record<string, unknown>) => Promise<unknown>
): Promise<unknown> {
  let lastError: unknown
  for (const target of targets) {
    try {
      return await requestForTarget(target)
    } catch (error) {
      lastError = error
      if (targets.length === 1 || !isApprovalTargetMiss(error)) throw error
    }
  }
  throw lastError
}

function workflowKey(item: unknown): string {
  if (!item || typeof item !== 'object' || Array.isArray(item)) return ''
  const record = item as Record<string, unknown>
  const namespace = typeof record.namespace === 'string' ? record.namespace : ''
  const name = typeof record.name === 'string' ? record.name : ''
  return namespace && name ? `${namespace}/${name}` : ''
}

function mergeWorkflowListResults(results: unknown[]): unknown {
  const items: unknown[] = []
  const seen = new Set<string>()
  for (const result of results) {
    const record = result && typeof result === 'object' ? (result as Record<string, unknown>) : {}
    const rawItems = Array.isArray(record.items) ? record.items : []
    for (const item of rawItems) {
      const key = workflowKey(item)
      if (key && seen.has(key)) continue
      if (key) seen.add(key)
      items.push(item)
    }
  }
  return { items, count: items.length }
}

function summarizeInputContract(inputContract: unknown): {
  requiresInput: boolean
  inputs: Array<Record<string, unknown>>
} {
  const contract =
    inputContract && typeof inputContract === 'object' && !Array.isArray(inputContract)
      ? (inputContract as Record<string, unknown>)
      : null
  const required = Array.isArray(contract?.required) ? contract.required.map(String) : []
  const properties =
    contract?.properties &&
    typeof contract.properties === 'object' &&
    !Array.isArray(contract.properties)
      ? (contract.properties as Record<string, unknown>)
      : {}
  const inputs = Object.entries(properties).map(([name, value]) => {
    const property =
      value && typeof value === 'object' && !Array.isArray(value)
        ? (value as Record<string, unknown>)
        : {}
    return {
      name,
      required: required.includes(name),
      ...(typeof property.description === 'string' ? { description: property.description } : {}),
      ...(Array.isArray(property.enum) ? { options: property.enum } : {}),
      ...(Object.prototype.hasOwnProperty.call(property, 'default')
        ? { default: property.default }
        : {}),
    }
  })
  return {
    requiresInput: inputs.some(input => input.required === true),
    inputs,
  }
}

function sanitizeWorkflowListForAuthenticatedChat(result: unknown): unknown {
  const record =
    result && typeof result === 'object' && !Array.isArray(result)
      ? (result as Record<string, unknown>)
      : {}
  const rawItems = Array.isArray(record.items) ? record.items : []
  const items = rawItems.map(item => {
    const workflow =
      item && typeof item === 'object' && !Array.isArray(item)
        ? (item as Record<string, unknown>)
        : {}
    const inputSummary = summarizeInputContract(workflow.inputContract)
    const targets = Array.isArray(workflow.targets)
      ? workflow.targets.flatMap(target => {
          const record =
            target && typeof target === 'object' && !Array.isArray(target)
              ? (target as Record<string, unknown>)
              : {}
          const kind = typeof record.kind === 'string' ? record.kind.trim() : ''
          const label = typeof record.label === 'string' ? record.label.trim() : ''
          return kind && label ? [{ kind, label }] : []
        })
      : []
    return {
      name: typeof workflow.name === 'string' ? workflow.name : '',
      ...(typeof workflow.description === 'string' ? { description: workflow.description } : {}),
      ...(targets.length > 0 ? { targets } : {}),
      ...(workflow.duplicateLabels === true ? { duplicateLabels: true } : {}),
      ...inputSummary,
    }
  })
  return { items, count: items.length }
}

function workflowNameFromRecord(record: Record<string, unknown>): string {
  if (typeof record.workflowName === 'string') return record.workflowName
  if (typeof record.name === 'string') return record.name
  if (typeof record.recipe === 'string') {
    const parts = record.recipe.split('/')
    return parts[parts.length - 1] || ''
  }
  return ''
}

function sanitizeRunSummaryForAuthenticatedChat(value: unknown): unknown {
  const run =
    value && typeof value === 'object' && !Array.isArray(value)
      ? (value as Record<string, unknown>)
      : null
  if (!run) return null
  return {
    ...(typeof run.phase === 'string' ? { phase: run.phase } : {}),
    ...(typeof run.triggeredAt === 'string' ? { triggeredAt: run.triggeredAt } : {}),
    ...(typeof run.startedAt === 'string' ? { startedAt: run.startedAt } : {}),
    ...(typeof run.completedAt === 'string' ? { completedAt: run.completedAt } : {}),
    ...(typeof run.message === 'string' ? { message: run.message } : {}),
  }
}

function sanitizeWorkflowStatusForAuthenticatedChat(result: unknown): unknown {
  const record =
    result && typeof result === 'object' && !Array.isArray(result)
      ? (result as Record<string, unknown>)
      : {}
  return {
    name: workflowNameFromRecord(record),
    ...(typeof record.phase === 'string' ? { phase: record.phase } : {}),
    ...(typeof record.workflowPhase === 'string' || record.workflowPhase === null
      ? { workflowPhase: record.workflowPhase }
      : {}),
    latestRun: sanitizeRunSummaryForAuthenticatedChat(record.latestRun),
  }
}

function sanitizeWorkflowHealthForAuthenticatedChat(result: unknown): unknown {
  const record =
    result && typeof result === 'object' && !Array.isArray(result)
      ? (result as Record<string, unknown>)
      : {}
  return {
    name: workflowNameFromRecord(record),
    ...(typeof record.phase === 'string' ? { phase: record.phase } : {}),
    ...(typeof record.workflowPhase === 'string' || record.workflowPhase === null
      ? { workflowPhase: record.workflowPhase }
      : {}),
    ...(typeof record.activeRuns === 'number' || record.activeRuns === null
      ? { activeRuns: record.activeRuns }
      : {}),
    lastRun: sanitizeRunSummaryForAuthenticatedChat(record.lastRun),
  }
}

function artifactRecords(value: unknown): Array<Record<string, unknown>> {
  const record =
    value && typeof value === 'object' && !Array.isArray(value)
      ? (value as Record<string, unknown>)
      : {}
  return Array.isArray(record.artifacts)
    ? record.artifacts.filter(
        (artifact): artifact is Record<string, unknown> =>
          Boolean(artifact) && typeof artifact === 'object' && !Array.isArray(artifact)
      )
    : []
}

function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms))
}

function pickWorkflowResultArtifact(
  artifacts: Array<Record<string, unknown>>,
  requestedName: string
): Record<string, unknown> | null {
  if (requestedName) {
    return artifacts.find(artifact => artifact.name === requestedName) ?? null
  }
  return (
    artifacts.find(
      artifact => typeof artifact.name === 'string' && artifact.name.toLowerCase().endsWith('.json')
    ) ??
    artifacts[0] ??
    null
  )
}

const AUTHENTICATED_RESULT_REDACTED_KEYS = new Set([
  'accesstoken',
  'apikey',
  'approvalid',
  'approvalrequestid',
  'authorization',
  'bearer',
  'clientsecret',
  'credential',
  'credentials',
  'grant',
  'grants',
  'hostref',
  'idempotencykey',
  'jwt',
  'namespace',
  'password',
  'privatekey',
  'refreshtoken',
  'runid',
  'secret',
  'secretkey',
  'scope',
  'scopes',
  'targetteamid',
  'targetuserid',
  'token',
  'workflowartifactname',
  'workflownamespace',
])

function normalizeResultKey(key: string): string {
  return key.toLowerCase().replace(/[^a-z0-9]/g, '')
}

const BEARER_TOKEN_RE = /\bBearer\s+[A-Za-z0-9._~+/=-]+\b/gi
const JWT_RE = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g

function sanitizeWorkflowResultStringForAuthenticatedChat(value: string): string {
  return value.replace(BEARER_TOKEN_RE, 'Bearer [REDACTED]').replace(JWT_RE, '[REDACTED_JWT]')
}

function sanitizeWorkflowResultValueForAuthenticatedChat(value: unknown): unknown {
  if (Array.isArray(value)) {
    return value.map(item => sanitizeWorkflowResultValueForAuthenticatedChat(item))
  }
  if (typeof value === 'string') {
    return sanitizeWorkflowResultStringForAuthenticatedChat(value)
  }
  if (!value || typeof value !== 'object') return value

  const output: Record<string, unknown> = {}
  for (const [key, rawValue] of Object.entries(value as Record<string, unknown>)) {
    if (AUTHENTICATED_RESULT_REDACTED_KEYS.has(normalizeResultKey(key))) continue
    output[key] = sanitizeWorkflowResultValueForAuthenticatedChat(rawValue)
  }
  return output
}

function sanitizeWorkflowResultContentForAuthenticatedChat(result: unknown): unknown {
  const record =
    result && typeof result === 'object' && !Array.isArray(result)
      ? (result as Record<string, unknown>)
      : null
  if (!record) return sanitizeWorkflowResultValueForAuthenticatedChat(result)

  if (Object.prototype.hasOwnProperty.call(record, 'content')) {
    return sanitizeWorkflowResultValueForAuthenticatedChat(record.content)
  }
  if (typeof record.contentText === 'string') {
    return { text: sanitizeWorkflowResultStringForAuthenticatedChat(record.contentText) }
  }
  if (typeof record.message === 'string') {
    return { message: sanitizeWorkflowResultStringForAuthenticatedChat(record.message) }
  }
  return sanitizeWorkflowResultValueForAuthenticatedChat(record)
}

function sanitizeWorkflowResultForAuthenticatedChat(params: {
  workflowName: string
  artifact: Record<string, unknown> | null
  result: unknown
}): unknown {
  const { workflowName, artifact, result } = params
  return {
    workflowName,
    artifactAvailable: Boolean(artifact),
    result: sanitizeWorkflowResultContentForAuthenticatedChat(result),
  }
}

function approvalTargetProperties(): Record<string, unknown> {
  return {
    targetUserId: {
      type: 'string',
      description: 'Optional user UUID whose approval/trigger visibility should scope the query.',
    },
    targetTeamId: {
      type: 'string',
      description: 'Optional team UUID whose approval/trigger visibility should scope the query.',
    },
  }
}

export class WorkflowResultTool extends WorkflowTool {
  private resultAttachments: Attachment[] | undefined

  name(): string {
    return 'workflow_result'
  }

  description(): string {
    return 'Read the result artifact for a workflow run already triggered in this conversation. Do not use this to run, start, trigger, execute, confirm a workflow started, monitor progress, check status/health/completion, inspect, or verify records in a connected MCP data system; use workflow_trigger for triggering, workflow_status/workflow_health for progress or status, and the relevant MCP read tool for data verification. Use this only after a trigger when the user asks for the workflow result artifact, a download, an artifact summary, or an artifact value that is not already present in the conversation. For MCP-backed records, do not call this when a workflow name, company, marker, public record reference, or other conversation-known business key can be used with the connected MCP read tool.'
  }

  parametersSchema(): Record<string, unknown> {
    return workflowTargetSchema({
      exposeNamespace: false,
      exposeTargetLabel: shouldResolveEffectiveWorkflowTargets(this.workflowCallerContext),
    })
  }

  async execute(params: Record<string, unknown>): Promise<ToolOutput> {
    const start = Date.now()
    this.resultAttachments = undefined
    try {
      const data = await this.run(params)
      return {
        content: JSON.stringify(data, null, 2),
        duration_ms: Date.now() - start,
        is_error: false,
        attachments: this.resultAttachments,
      }
    } catch (err) {
      return {
        content: `Error: ${err instanceof Error ? err.message : String(err)}`,
        duration_ms: Date.now() - start,
        is_error: true,
      }
    }
  }

  async executeForRun(workflowRunId: string, artifactName?: string): Promise<ToolOutput> {
    const start = Date.now()
    this.resultAttachments = undefined
    try {
      const data = await this.runForRun(workflowRunId, artifactName)
      return {
        content: JSON.stringify(data, null, 2),
        duration_ms: Date.now() - start,
        is_error: false,
        attachments: this.resultAttachments,
      }
    } catch (err) {
      return {
        content: `Error: ${err instanceof Error ? err.message : String(err)}`,
        duration_ms: Date.now() - start,
        is_error: true,
      }
    }
  }

  private authenticatedConversationTarget(): Record<string, unknown> {
    const conversationId = this.workflowCallerContext?.conversationId?.trim()
    if (
      !conversationId ||
      (!this.workflowCallerContext?.targetUserId && !this.workflowCallerContext?.targetTeamId)
    ) {
      throw new Error('workflow_result is available only in an authenticated workflow conversation')
    }
    return {
      ...(this.workflowCallerContext.targetUserId
        ? { targetUserId: this.workflowCallerContext.targetUserId }
        : {}),
      ...(this.workflowCallerContext.targetTeamId
        ? { targetTeamId: this.workflowCallerContext.targetTeamId }
        : {}),
      workflowConversationId: conversationId,
    }
  }

  private async readWorkflowResult(params: {
    listPath: string
    downloadPath: (artifactName: string) => string
    fallbackWorkflowName: string
    requestedArtifactName?: string
  }): Promise<{
    workflowName: string
    artifact: Record<string, unknown> | null
    result: unknown
  }> {
    let listResult: unknown
    let listRecord: Record<string, unknown> = {}
    let canonicalWorkflowName = params.fallbackWorkflowName
    let artifact: Record<string, unknown> | null = null
    let lastListError: unknown
    const pollAttempts = workflowResultArtifactPollAttempts(this.getEnv)
    const pollIntervalMs = workflowResultArtifactPollIntervalMs(this.getEnv)
    for (let attempt = 0; attempt < pollAttempts; attempt++) {
      try {
        listResult = await this.client.request(params.listPath)
        lastListError = undefined
        listRecord =
          listResult && typeof listResult === 'object' && !Array.isArray(listResult)
            ? (listResult as Record<string, unknown>)
            : {}
        canonicalWorkflowName = workflowNameFromRecord(listRecord) || params.fallbackWorkflowName
        artifact = pickWorkflowResultArtifact(
          artifactRecords(listResult),
          params.requestedArtifactName ?? ''
        )
        if (artifact) break
      } catch (error) {
        if (!isRetryableWorkflowResultArtifactListError(error)) throw error
        lastListError = error
      }
      if (attempt < pollAttempts - 1) {
        await sleep(pollIntervalMs)
      }
    }
    if (!artifact) {
      return {
        workflowName: canonicalWorkflowName,
        artifact: null,
        result: {
          artifacts: [],
          message: lastListError
            ? 'Workflow result artifacts are still being prepared for this run.'
            : 'No workflow result artifacts are available for this run yet.',
        },
      }
    }
    const artifactName = typeof artifact.name === 'string' ? artifact.name : ''
    const { contentResult, attachment } = await workflowResultArtifactDownload({
      client: this.client,
      downloadPath: params.downloadPath(artifactName),
      artifactName,
      getEnv: this.getEnv,
    })
    this.resultAttachments = attachment ? [attachment] : undefined
    console.log(
      `[WorkflowResult] Artifact attachment count for ${artifactName}: ${
        this.resultAttachments?.length ?? 0
      }`
    )
    return {
      workflowName: canonicalWorkflowName,
      artifact,
      result: contentResult,
    }
  }

  private async runForRun(workflowRunId: string, artifactName?: string): Promise<unknown> {
    const normalizedRunId = workflowRunId.trim()
    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(normalizedRunId)) {
      throw new Error('Invalid workflow run ID')
    }
    const target = this.authenticatedConversationTarget()
    const result = await this.readWorkflowResult({
      listPath: appendApprovalTargetQuery(
        `/api/v1/workflows/runs/${encodeURIComponent(normalizedRunId)}/artifacts`,
        target
      ),
      downloadPath: name =>
        appendApprovalTargetQuery(
          `/api/v1/workflows/runs/${encodeURIComponent(
            normalizedRunId
          )}/artifacts/${encodeURIComponent(name)}/download`,
          target
        ),
      fallbackWorkflowName: 'workflow',
      ...(artifactName?.trim() ? { requestedArtifactName: artifactName.trim() } : {}),
    })
    return sanitizeWorkflowResultForAuthenticatedChat(result)
  }

  async run(params: Record<string, unknown>): Promise<unknown> {
    const conversationId = this.workflowCallerContext?.conversationId?.trim()
    const authenticated = Boolean(
      conversationId &&
      (this.workflowCallerContext?.targetUserId || this.workflowCallerContext?.targetTeamId)
    )
    if (!authenticated || !conversationId) {
      throw new Error('workflow_result is available only in an authenticated workflow conversation')
    }
    const { namespace, name } = requireWorkflowRef(params, WORKFLOW_RECIPE_NAMESPACE)
    if (getString(params, 'runId')) {
      throw new Error('workflow_result run id is derived from the authenticated conversation')
    }
    let targets: Record<string, unknown>[]
    if (shouldResolveEffectiveWorkflowTargets(this.workflowCallerContext)) {
      rejectModelSuppliedApprovalTarget(params)
      const resolution = await resolveEffectiveWorkflowTarget(
        this.client,
        this.workflowCallerContext,
        name,
        getString(params, 'targetLabel')
      )
      if (resolution.kind !== 'unique') {
        return sanitizeWorkflowResultForAuthenticatedChat({
          workflowName: name,
          artifact: null,
          result: nonUniqueEffectiveTargetResponse(name, resolution),
        })
      }
      targets = [{ ...resolution.approvalTarget, workflowConversationId: conversationId }]
    } else {
      targets = approvalTargetParamSet(params, this.workflowCallerContext).map(target => ({
        ...target,
        workflowConversationId: conversationId,
      }))
    }
    const result = await requestWithApprovalTargetFallback(targets, async target => {
      const listPath = appendApprovalTargetQuery(
        `/api/v1/workflows/${encodeURIComponent(namespace)}/${encodeURIComponent(
          name
        )}/runs/latest/artifacts`,
        target
      )
      return this.readWorkflowResult({
        listPath,
        downloadPath: artifactName =>
          appendApprovalTargetQuery(
            `/api/v1/workflows/${encodeURIComponent(namespace)}/${encodeURIComponent(
              name
            )}/runs/latest/artifacts/${encodeURIComponent(artifactName)}/download`,
            target
          ),
        fallbackWorkflowName: name,
      })
    })

    return sanitizeWorkflowResultForAuthenticatedChat(
      result as {
        workflowName: string
        artifact: Record<string, unknown> | null
        result: unknown
      }
    )
  }
}

export class WorkflowListTool extends WorkflowTool {
  name(): string {
    return 'workflow_list'
  }

  description(): string {
    return 'List workflow recipes visible to this runtime host.'
  }

  parametersSchema(): Record<string, unknown> {
    if (this.workflowCallerContext?.targetUserId || this.workflowCallerContext?.targetTeamId) {
      return {
        type: 'object',
        properties: {},
        required: [],
      }
    }
    return { type: 'object', properties: approvalTargetProperties(), required: [] }
  }

  async run(params: Record<string, unknown>): Promise<unknown> {
    if (shouldResolveEffectiveWorkflowTargets(this.workflowCallerContext)) {
      rejectModelSuppliedApprovalTarget(params)
      const result = await requestEffectiveWorkflowList(this.client, this.workflowCallerContext)
      return sanitizeWorkflowListForAuthenticatedChat(result)
    }

    const targets = approvalTargetParamSet(params, this.workflowCallerContext)
    const results = await Promise.all(
      targets.map(target =>
        this.client.request(appendApprovalTargetQuery('/api/v1/workflows', target))
      )
    )
    const result = results.length === 1 ? results[0] : mergeWorkflowListResults(results)
    return this.workflowCallerContext ? sanitizeWorkflowListForAuthenticatedChat(result) : result
  }
}

export class WorkflowStatusTool extends WorkflowTool {
  name(): string {
    return 'workflow_status'
  }

  description(): string {
    return 'Get workflow metadata, status, and latest run summary.'
  }

  parametersSchema(): Record<string, unknown> {
    if (this.workflowCallerContext?.targetUserId || this.workflowCallerContext?.targetTeamId) {
      return workflowTargetSchema({
        exposeNamespace: false,
        exposeTargetLabel: shouldResolveEffectiveWorkflowTargets(this.workflowCallerContext),
      })
    }
    const schema = workflowTargetSchema()
    return {
      ...schema,
      properties: {
        ...(schema.properties as Record<string, unknown>),
        ...approvalTargetProperties(),
      },
    }
  }

  async run(params: Record<string, unknown>): Promise<unknown> {
    const { namespace, name } = requireWorkflowRef(
      params,
      this.workflowCallerContext ? WORKFLOW_RECIPE_NAMESPACE : undefined
    )
    let targets: Record<string, unknown>[]
    if (shouldResolveEffectiveWorkflowTargets(this.workflowCallerContext)) {
      rejectModelSuppliedApprovalTarget(params)
      const resolution = await resolveEffectiveWorkflowTarget(
        this.client,
        this.workflowCallerContext,
        name,
        getString(params, 'targetLabel')
      )
      if (resolution.kind !== 'unique') return nonUniqueEffectiveTargetResponse(name, resolution)
      targets = [resolution.approvalTarget]
    } else {
      targets = approvalTargetParamSet(params, this.workflowCallerContext)
    }
    targets = attachWorkflowConversation(targets, this.workflowCallerContext)
    const result = await requestWithApprovalTargetFallback(targets, target =>
      this.client.request(
        appendApprovalTargetQuery(
          `/api/v1/workflows/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}`,
          target
        )
      )
    )
    return this.workflowCallerContext ? sanitizeWorkflowStatusForAuthenticatedChat(result) : result
  }
}

export class WorkflowHealthTool extends WorkflowTool {
  name(): string {
    return 'workflow_health'
  }

  description(): string {
    return 'Get workflow health signals and active-run summary.'
  }

  parametersSchema(): Record<string, unknown> {
    if (this.workflowCallerContext?.targetUserId || this.workflowCallerContext?.targetTeamId) {
      return workflowTargetSchema({
        exposeNamespace: false,
        exposeTargetLabel: shouldResolveEffectiveWorkflowTargets(this.workflowCallerContext),
      })
    }
    const schema = workflowTargetSchema()
    return {
      ...schema,
      properties: {
        ...(schema.properties as Record<string, unknown>),
        ...approvalTargetProperties(),
      },
    }
  }

  async run(params: Record<string, unknown>): Promise<unknown> {
    const { namespace, name } = requireWorkflowRef(
      params,
      this.workflowCallerContext ? WORKFLOW_RECIPE_NAMESPACE : undefined
    )
    let targets: Record<string, unknown>[]
    if (shouldResolveEffectiveWorkflowTargets(this.workflowCallerContext)) {
      rejectModelSuppliedApprovalTarget(params)
      const resolution = await resolveEffectiveWorkflowTarget(
        this.client,
        this.workflowCallerContext,
        name,
        getString(params, 'targetLabel')
      )
      if (resolution.kind !== 'unique') return nonUniqueEffectiveTargetResponse(name, resolution)
      targets = [resolution.approvalTarget]
    } else {
      targets = approvalTargetParamSet(params, this.workflowCallerContext)
    }
    targets = attachWorkflowConversation(targets, this.workflowCallerContext)
    const result = await requestWithApprovalTargetFallback(targets, target =>
      this.client.request(
        appendApprovalTargetQuery(
          `/api/v1/workflows/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}/health`,
          target
        )
      )
    )
    return this.workflowCallerContext ? sanitizeWorkflowHealthForAuthenticatedChat(result) : result
  }
}