@foundation0/git 1.2.5 → 1.3.1

package/src/actions-api.ts

@@ -1,517 +1,738 @@
-import type { GitServiceApi, GitServiceApiExecutionResult, GitServiceApiMethod } from './git-service-api'
-import type { GitApiFeatureMapping } from './platform/gitea-adapter'
-import type { GitPlatformConfig } from './platform/config'
-
-const DEFAULT_LOG_TAIL_LINES = 200
-const DEFAULT_HTTP_TIMEOUT_MS = 60_000
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
+import type { GitServiceApi, GitServiceApiExecutionResult, GitServiceApiMethod } from './git-service-api'
+import type { GitApiFeatureMapping } from './platform/gitea-adapter'
+import type { GitPlatformConfig } from './platform/config'
+
+const DEFAULT_LOG_TAIL_LINES = 200
+const DEFAULT_HTTP_TIMEOUT_MS = 60_000
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const toTrimmedString = (value: unknown): string | null => {
+  if (value === null || value === undefined) {
+    return null
+  }
+
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) return null
+    const asText = String(Math.trunc(value)).trim()
+    return asText.length > 0 ? asText : null
+  }
+
+  if (typeof value === 'bigint') {
+    const asText = value.toString().trim()
+    return asText.length > 0 ? asText : null
+  }
+
+  if (typeof value !== 'string') {
+    return null
+  }
+
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+const toPositiveInteger = (value: unknown): number | null => {
+  const candidate = Number(value)
+  if (!Number.isFinite(candidate) || candidate <= 0 || Math.floor(candidate) !== candidate) {
+    return null
+  }
+  return candidate
+}
+
+const buildApiBase = (host: string): string => {
+  const sanitized = host.replace(/\/$/, '')
+  if (sanitized.endsWith('/api/v1')) {
+    return sanitized
+  }
+  return `${sanitized}/api/v1`
+}
+
+const toQueryArray = (query: Record<string, string | number | boolean>): string[] =>
+  Object.entries(query).map(([key, value]) => `${key}=${String(value)}`)
+
+const toHeaderRecord = (headers: string[]): Record<string, string> =>
+  Object.fromEntries(
+    headers
+      .map((entry) => {
+        const separatorIndex = entry.indexOf(':')
+        if (separatorIndex < 0) {
+          return null
+        }
+        const name = entry.slice(0, separatorIndex).trim()
+        const value = entry.slice(separatorIndex + 1).trim()
+        return [name, value]
+      })
+      .filter((entry): entry is [string, string] => Boolean(entry)),
+  )
+
+type RawCall = {
+  args: string[]
+  options: Record<string, unknown>
+}
+
+const splitArgsAndOptions = (rawArgs: unknown[]): RawCall => {
+  if (rawArgs.length === 0 || !isRecord(rawArgs[rawArgs.length - 1])) {
+    return {
+      args: rawArgs.map((value) => String(value)),
+      options: {},
+    }
+  }
+
+  const last = rawArgs[rawArgs.length - 1] as Record<string, unknown>
+  return {
+    args: rawArgs.slice(0, -1).map((value) => String(value)),
+    options: { ...last },
+  }
+}
+
+type Scope = {
+  owner?: string
+  repo?: string
+  options: Record<string, unknown>
+}
+
+export interface GitActionsApiDefaults {
+  defaultOwner?: string
+  defaultRepo?: string
+}
+
+export interface GitActionsApiContext {
+  config: Pick<GitPlatformConfig, 'giteaHost' | 'giteaToken' | 'platform'>
+  defaults?: GitActionsApiDefaults
+  requestTimeoutMs?: number
+  log?: (message: string) => void
+}
+
+const normalizeScopeArgs = (ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown): Scope => {
+  const options: Record<string, unknown> = {}
+  let owner: string | undefined
+  let repo: string | undefined
+
+  const absorb = (value: unknown): string | undefined => {
+    if (value === undefined || value === null) {
+      return undefined
+    }
+
+    if (isRecord(value)) {
+      Object.assign(options, value)
+      return undefined
+    }
+
+    const asText = String(value).trim()
+    return asText.length > 0 ? asText : undefined
+  }
+
+  owner = absorb(ownerOrOptions)
+  repo = absorb(repoOrOptions)
+
+  if (isRecord(maybeOptions)) {
+    Object.assign(options, maybeOptions)
+  }
+
+  return {
+    ...(owner ? { owner } : {}),
+    ...(repo ? { repo } : {}),
+    options,
+  }
+}
+
+const resolveOwnerRepo = (
+  scope: Pick<Scope, 'owner' | 'repo'>,
+  defaults: GitActionsApiDefaults,
+): { owner: string; repo: string } => {
+  const owner = scope.owner ?? defaults.defaultOwner
+  const repo = scope.repo ?? defaults.defaultRepo
+
+  if (!owner || !repo) {
+    throw new Error(
+      'Owner/repo is required. Pass owner and repo args or set defaultOwner/defaultRepo when creating the API.',
+    )
+  }
+
+  return { owner, repo }
+}
+
+const resolveOwnerRepoFromArgs = (
+  args: string[],
+  scope: Pick<Scope, 'owner' | 'repo'>,
+  defaults: GitActionsApiDefaults,
+): { owner: string; repo: string; rest: string[] } => {
+  if (scope.owner || scope.repo) {
+    const resolved = resolveOwnerRepo(scope, defaults)
+    return { ...resolved, rest: args }
+  }
+
+  if (args.length >= 2) {
+    return { owner: args[0], repo: args[1], rest: args.slice(2) }
+  }
+
+  if (args.length === 1) {
+    const split = args[0].split('/')
+    if (split.length === 2 && split[0] && split[1]) {
+      return { owner: split[0], repo: split[1], rest: [] }
+    }
+  }
+
+  const resolved = resolveOwnerRepo({}, defaults)
+  return { ...resolved, rest: args }
+}
+
+type NormalizedActionsState = 'success' | 'failure' | 'pending'
+
+const normalizeActionsState = (raw: unknown): NormalizedActionsState => {
+  const value = toTrimmedString(raw).toLowerCase()
+  if (value === 'success') return 'success'
+  if (value === 'failure' || value === 'failed' || value === 'error') return 'failure'
+  if (value === 'cancelled' || value === 'canceled') return 'failure'
+  if (value === 'skipped') return 'success'
+  if (value === 'running' || value === 'in_progress' || value === 'queued' || value === 'waiting') return 'pending'
+  if (value === 'pending') return 'pending'
+  return 'pending'
+}
+
+const resolveOwnerRepoAndId = (
+  rawArgs: unknown[],
+  defaults: GitActionsApiDefaults,
+): { owner: string; repo: string; id: string; options: Record<string, unknown> } => {
+  const parsed = splitArgsAndOptions(rawArgs)
+  const args = parsed.args.map((value) => value.trim()).filter((value) => value.length > 0)
+
+  if (args.length === 0) {
+    throw new Error('ID is required.')
+  }
+
+  if (args.length === 1) {
+    const { owner, repo } = resolveOwnerRepo({}, defaults)
+    return { owner, repo, id: args[0], options: parsed.options }
+  }
+
+  if (args.length === 2) {
+    if (args[0].includes('/')) {
+      const split = args[0].split('/')
+      if (split.length === 2 && split[0] && split[1]) {
+        return { owner: split[0], repo: split[1], id: args[1], options: parsed.options }
+      }
+    }
+
+    throw new Error(
+      'Ambiguous arguments. Pass <id> (and rely on defaults), or pass <owner> <repo> <id>, or pass <owner/repo> <id>.',
+    )
+  }
+
+  return { owner: args[0], repo: args[1], id: args[2], options: parsed.options }
+}
+
+const resolveTimeoutMs = (value: unknown, fallback: number): number => {
+  const parsed = toPositiveInteger(value)
+  return parsed ?? fallback
+}
+
+const readTextBody = async (response: Response): Promise<string> => {
+  try {
+    return await response.text()
+  } catch {
+    return ''
+  }
+}
+
+const readBody = async (response: Response): Promise<unknown> => {
+  const contentType = response.headers.get('content-type') ?? ''
+  const text = await readTextBody(response)
+  if (contentType.toLowerCase().includes('application/json')) {
+    try {
+      return JSON.parse(text)
+    } catch {
+      return text
+    }
+  }
+  return text
+}
+
+const requestGitea = async (
+  ctx: GitActionsApiContext,
+  featurePath: string[],
+  owner: string,
+  repo: string,
+  method: string,
+  pathTail: string[],
+  options: Record<string, unknown> = {},
+  requestInitOverrides: Partial<RequestInit> = {},
+): Promise<GitServiceApiExecutionResult<unknown>> => {
+  if (ctx.config.platform !== 'GITEA') {
+    throw new Error(`Actions API only supports GITEA platform, got ${ctx.config.platform}`)
+  }
+
+  const apiBase = buildApiBase(ctx.config.giteaHost)
+  const mappedPath = ['repos', owner, repo, 'actions', ...pathTail]
+
+  const query = isRecord(options.query) ? (options.query as Record<string, unknown>) : {}
+  const queryRecord: Record<string, string | number | boolean> = {}
+  for (const [key, value] of Object.entries(query)) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      queryRecord[key] = value
+    }
+  }
+
+  const url = new URL(`${apiBase}/${mappedPath.join('/')}`)
+  for (const [key, value] of Object.entries(queryRecord)) {
+    url.searchParams.set(key, String(value))
+  }
+
+  const headersList: string[] = []
+  headersList.push('Accept: */*')
+  if (ctx.config.giteaToken) {
+    headersList.push(`Authorization: token ${ctx.config.giteaToken}`)
+  }
+
+  const headers = toHeaderRecord(headersList)
+
+  const requestTimeoutMs = resolveTimeoutMs(options.requestTimeoutMs ?? ctx.requestTimeoutMs, DEFAULT_HTTP_TIMEOUT_MS)
+  const timeoutSignal =
+    requestTimeoutMs > 0 && typeof (AbortSignal as unknown as { timeout?: (ms: number) => AbortSignal }).timeout === 'function'
+      ? (AbortSignal as unknown as { timeout: (ms: number) => AbortSignal }).timeout(requestTimeoutMs)
+      : null
+  const controller = !timeoutSignal && requestTimeoutMs > 0 ? new AbortController() : null
+  const timeoutId = controller ? setTimeout(() => controller.abort(), requestTimeoutMs) : null
+
+  try {
+    ctx.log?.(`actions:http:request ${method.toUpperCase()} ${url.toString()}`)
+    const response = await fetch(url.toString(), {
+      method: method.toUpperCase(),
+      headers,
+      ...(timeoutSignal ? { signal: timeoutSignal } : {}),
+      ...(controller ? { signal: controller.signal } : {}),
+      ...requestInitOverrides,
+    })
+
+    const body = await readBody(response)
+    const responseHeaders: Record<string, string> = {}
+    try {
+      response.headers.forEach((value, key) => {
+        responseHeaders[key.toLowerCase()] = value
+      })
+    } catch {
+      // best effort
+    }
+
+    const mapping: GitApiFeatureMapping = {
+      platform: 'GITEA',
+      featurePath,
+      mappedPath,
+      method: method.toUpperCase(),
+      query: toQueryArray(queryRecord),
+      headers: headersList,
+      apiBase,
+      swaggerPath: `/${mappedPath.join('/')}`,
+      mapped: true,
+      reason: 'Direct Gitea Actions API call',
+    }
+
+    return {
+      mapping,
+      request: {
+        url: url.toString(),
+        method: method.toUpperCase(),
+        headers,
+        query: toQueryArray(queryRecord),
+      },
+      response: {
+        headers: responseHeaders,
+      },
+      status: response.status,
+      ok: response.ok,
+      body,
+    }
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId)
+    }
+  }
+}
+
+const tailText = (input: string, options: { contains?: string; maxLines?: number; maxBytes?: number }): string => {
+  const contains = toTrimmedString(options.contains ?? null) ?? null
+  const maxLines = toPositiveInteger(options.maxLines) ?? DEFAULT_LOG_TAIL_LINES
+  const maxBytes = toPositiveInteger(options.maxBytes)
+
+  let text = input
+
+  if (contains) {
+    text = text
+      .split(/\r?\n/g)
+      .filter((line) => line.includes(contains))
+      .join('\n')
+  }
+
+  if (maxLines > 0) {
+    const lines = text.split(/\r?\n/g)
+    text = lines.slice(Math.max(0, lines.length - maxLines)).join('\n')
+  }
+
+  if (maxBytes && maxBytes > 0) {
+    const buf = Buffer.from(text, 'utf8')
+    if (buf.length > maxBytes) {
+      text = buf.subarray(buf.length - maxBytes).toString('utf8')
+    }
+  }
 
-const toTrimmedString = (value: unknown): string | null => {
-  if (typeof value !== 'string') {
-    return null
-  }
-  const trimmed = value.trim()
-  return trimmed.length > 0 ? trimmed : null
+  return text
 }
 
-const toPositiveInteger = (value: unknown): number | null => {
-  const candidate = Number(value)
-  if (!Number.isFinite(candidate) || candidate <= 0 || Math.floor(candidate) !== candidate) {
+const tryParseJsonLikeText = (value: string): unknown | null => {
+  try {
+    return JSON.parse(value) as unknown
+  } catch {
     return null
   }
-  return candidate
-}
-
-const buildApiBase = (host: string): string => {
-  const sanitized = host.replace(/\/$/, '')
-  if (sanitized.endsWith('/api/v1')) {
-    return sanitized
-  }
-  return `${sanitized}/api/v1`
 }
 
-const toQueryArray = (query: Record<string, string | number | boolean>): string[] =>
-  Object.entries(query).map(([key, value]) => `${key}=${String(value)}`)
-
-const toHeaderRecord = (headers: string[]): Record<string, string> =>
-  Object.fromEntries(
-    headers
-      .map((entry) => {
-        const separatorIndex = entry.indexOf(':')
-        if (separatorIndex < 0) {
-          return null
-        }
-        const name = entry.slice(0, separatorIndex).trim()
-        const value = entry.slice(separatorIndex + 1).trim()
-        return [name, value]
-      })
-      .filter((entry): entry is [string, string] => Boolean(entry)),
-  )
-
-type RawCall = {
-  args: string[]
-  options: Record<string, unknown>
-}
-
-const splitArgsAndOptions = (rawArgs: unknown[]): RawCall => {
-  if (rawArgs.length === 0 || !isRecord(rawArgs[rawArgs.length - 1])) {
-    return {
-      args: rawArgs.map((value) => String(value)),
-      options: {},
+const extractErrorMessage = (body: unknown): string | null => {
+  if (isRecord(body)) {
+    if (typeof body.message === 'string' && body.message.trim().length > 0) {
+      return body.message.trim()
     }
-  }
-
-  const last = rawArgs[rawArgs.length - 1] as Record<string, unknown>
-  return {
-    args: rawArgs.slice(0, -1).map((value) => String(value)),
-    options: { ...last },
-  }
-}
-
-type Scope = {
-  owner?: string
-  repo?: string
-  options: Record<string, unknown>
-}
-
-export interface GitActionsApiDefaults {
-  defaultOwner?: string
-  defaultRepo?: string
-}
-
-export interface GitActionsApiContext {
-  config: Pick<GitPlatformConfig, 'giteaHost' | 'giteaToken' | 'platform'>
-  defaults?: GitActionsApiDefaults
-  requestTimeoutMs?: number
-  log?: (message: string) => void
-}
-
-const normalizeScopeArgs = (ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown): Scope => {
-  const options: Record<string, unknown> = {}
-  let owner: string | undefined
-  let repo: string | undefined
-
-  const absorb = (value: unknown): string | undefined => {
-    if (value === undefined || value === null) {
-      return undefined
+    if (typeof body.error === 'string' && body.error.trim().length > 0) {
+      return body.error.trim()
     }
-
-    if (isRecord(value)) {
-      Object.assign(options, value)
-      return undefined
+    if (isRecord(body.error)) {
+      const nestedMessage = extractErrorMessage(body.error)
+      if (nestedMessage) return nestedMessage
     }
-
-    const asText = String(value).trim()
-    return asText.length > 0 ? asText : undefined
   }
 
-  owner = absorb(ownerOrOptions)
-  repo = absorb(repoOrOptions)
-
-  if (isRecord(maybeOptions)) {
-    Object.assign(options, maybeOptions)
-  }
-
-  return {
-    ...(owner ? { owner } : {}),
-    ...(repo ? { repo } : {}),
-    options,
-  }
-}
-
-const resolveOwnerRepo = (
-  scope: Pick<Scope, 'owner' | 'repo'>,
-  defaults: GitActionsApiDefaults,
-): { owner: string; repo: string } => {
-  const owner = scope.owner ?? defaults.defaultOwner
-  const repo = scope.repo ?? defaults.defaultRepo
-
-  if (!owner || !repo) {
-    throw new Error(
-      'Owner/repo is required. Pass owner and repo args or set defaultOwner/defaultRepo when creating the API.',
-    )
+  if (typeof body !== 'string') {
+    return null
   }
 
-  return { owner, repo }
-}
-
-const resolveOwnerRepoFromArgs = (
-  args: string[],
-  scope: Pick<Scope, 'owner' | 'repo'>,
-  defaults: GitActionsApiDefaults,
-): { owner: string; repo: string; rest: string[] } => {
-  if (scope.owner || scope.repo) {
-    const resolved = resolveOwnerRepo(scope, defaults)
-    return { ...resolved, rest: args }
+  const trimmed = body.trim()
+  if (!trimmed) {
+    return null
   }
 
-  if (args.length >= 2) {
-    return { owner: args[0], repo: args[1], rest: args.slice(2) }
-  }
+  const parsed =
+    trimmed.startsWith('{') || trimmed.startsWith('[')
+      ? tryParseJsonLikeText(trimmed)
+      : null
 
-  if (args.length === 1) {
-    const split = args[0].split('/')
-    if (split.length === 2 && split[0] && split[1]) {
-      return { owner: split[0], repo: split[1], rest: [] }
+  if (parsed && isRecord(parsed)) {
+    const parsedMessage = extractErrorMessage(parsed)
+    if (parsedMessage) {
+      return parsedMessage
     }
   }
 
-  const resolved = resolveOwnerRepo({}, defaults)
-  return { ...resolved, rest: args }
-}
-
-const resolveOwnerRepoAndId = (
-  rawArgs: unknown[],
-  defaults: GitActionsApiDefaults,
-): { owner: string; repo: string; id: string; options: Record<string, unknown> } => {
-  const parsed = splitArgsAndOptions(rawArgs)
-  const args = parsed.args.map((value) => value.trim()).filter((value) => value.length > 0)
-
-  if (args.length === 0) {
-    throw new Error('ID is required.')
-  }
-
-  if (args.length === 1) {
-    const { owner, repo } = resolveOwnerRepo({}, defaults)
-    return { owner, repo, id: args[0], options: parsed.options }
-  }
-
-  if (args.length === 2) {
-    if (args[0].includes('/')) {
-      const split = args[0].split('/')
-      if (split.length === 2 && split[0] && split[1]) {
-        return { owner: split[0], repo: split[1], id: args[1], options: parsed.options }
-      }
-    }
-
-    throw new Error(
-      'Ambiguous arguments. Pass <id> (and rely on defaults), or pass <owner> <repo> <id>, or pass <owner/repo> <id>.',
-    )
+  const firstLine = trimmed.split(/\r?\n/, 1)[0]?.trim() ?? ''
+  if (firstLine === '{' || firstLine === '[') {
+    return null
   }
 
-  return { owner: args[0], repo: args[1], id: args[2], options: parsed.options }
+  return firstLine.length > 0 ? firstLine : null
 }
 
-const resolveTimeoutMs = (value: unknown, fallback: number): number => {
-  const parsed = toPositiveInteger(value)
-  return parsed ?? fallback
-}
+const shouldTryNextJobIdCandidate = (status: number): boolean => status >= 500 || status === 404 || status === 422
+
+const collectJobIdCandidates = (run: Record<string, unknown>): string[] => {
+  const nestedJobRecord = isRecord(run.job) ? run.job : {}
+  const candidates = [
+    run.job_id,
+    run.jobId,
+    run.task_id,
+    run.taskId,
+    nestedJobRecord.id,
+    nestedJobRecord.job_id,
+    nestedJobRecord.jobId,
+    run.id,
+  ]
 
-const readTextBody = async (response: Response): Promise<string> => {
-  try {
-    return await response.text()
-  } catch {
-    return ''
-  }
+  const normalized = candidates.map((candidate) => toTrimmedString(candidate)).filter((value): value is string => Boolean(value))
+  return Array.from(new Set(normalized))
 }
 
-const readBody = async (response: Response): Promise<unknown> => {
-  const contentType = response.headers.get('content-type') ?? ''
-  const text = await readTextBody(response)
-  if (contentType.toLowerCase().includes('application/json')) {
-    try {
-      return JSON.parse(text)
-    } catch {
-      return text
-    }
-  }
-  return text
+type JobLogLookupAttempt = {
+  jobId: string
+  status: number
+  ok: boolean
+  message: string | null
 }
 
-const requestGitea = async (
-  ctx: GitActionsApiContext,
-  featurePath: string[],
-  owner: string,
-  repo: string,
-  method: string,
-  pathTail: string[],
-  options: Record<string, unknown> = {},
-  requestInitOverrides: Partial<RequestInit> = {},
-): Promise<GitServiceApiExecutionResult<unknown>> => {
-  if (ctx.config.platform !== 'GITEA') {
-    throw new Error(`Actions API only supports GITEA platform, got ${ctx.config.platform}`)
-  }
-
-  const apiBase = buildApiBase(ctx.config.giteaHost)
-  const mappedPath = ['repos', owner, repo, 'actions', ...pathTail]
-
-  const query = isRecord(options.query) ? (options.query as Record<string, unknown>) : {}
-  const queryRecord: Record<string, string | number | boolean> = {}
-  for (const [key, value] of Object.entries(query)) {
-    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-      queryRecord[key] = value
-    }
-  }
-
-  const url = new URL(`${apiBase}/${mappedPath.join('/')}`)
-  for (const [key, value] of Object.entries(queryRecord)) {
-    url.searchParams.set(key, String(value))
-  }
+const buildJobLogsFailureBody = (params: {
+  owner: string
+  repo: string
+  headSha: string
+  runNumber: number
+  workflowName?: string | null
+  attempts: JobLogLookupAttempt[]
+  upstreamBody: unknown
+  maxLines: number
+}): Record<string, unknown> => {
+  const workflowSegment =
+    params.workflowName && params.workflowName.trim().length > 0 ? ` workflowName=${params.workflowName.trim()}` : ''
 
-  const headersList: string[] = []
-  headersList.push('Accept: */*')
-  if (ctx.config.giteaToken) {
-    headersList.push(`Authorization: token ${ctx.config.giteaToken}`)
+  return {
+    message: `Auto-resolution failed for Actions logs: head_sha=${params.headSha} run_number=${params.runNumber}${workflowSegment}. None of the candidate ids worked for /actions/jobs/{job_id}/logs on this Gitea instance.`,
+    hint: `Use explicit job_id flow: 1) repo.actions.tasks.list { owner, repo, query:{ limit: 100 } } 2) extract a concrete job_id from workflow_runs (or from the Gitea UI run page) 3) repo.actions.jobs.logsTail { args:["<job_id>"], owner, repo, maxLines:${params.maxLines} }.`,
+    suggestedCalls: [
+      {
+        tool: 'repo.actions.tasks.list',
+        args: [params.owner, params.repo],
+        options: { query: { limit: 100 } },
+      },
+      {
+        tool: 'repo.actions.jobs.logsTail',
+        args: ['<job_id>'],
+        options: { owner: params.owner, repo: params.repo, maxLines: params.maxLines },
+      },
+    ],
+    autoResolutionNote: 'workflow_runs.id/task_id is not guaranteed to equal job_id across all Gitea versions/configurations.',
+    attemptedJobIds: params.attempts.map((attempt) => ({
+      jobId: attempt.jobId,
+      status: attempt.status,
+      ...(attempt.message ? { message: attempt.message } : {}),
+    })),
+    upstream: params.upstreamBody,
   }
+}
 
-  const headers = toHeaderRecord(headersList)
-
-  const requestTimeoutMs = resolveTimeoutMs(options.requestTimeoutMs ?? ctx.requestTimeoutMs, DEFAULT_HTTP_TIMEOUT_MS)
-  const timeoutSignal =
-    requestTimeoutMs > 0 && typeof (AbortSignal as unknown as { timeout?: (ms: number) => AbortSignal }).timeout === 'function'
-      ? (AbortSignal as unknown as { timeout: (ms: number) => AbortSignal }).timeout(requestTimeoutMs)
-      : null
-  const controller = !timeoutSignal && requestTimeoutMs > 0 ? new AbortController() : null
-  const timeoutId = controller ? setTimeout(() => controller.abort(), requestTimeoutMs) : null
+const fetchJobLogsByCandidates = async (params: {
+  ctx: GitActionsApiContext
+  owner: string
+  repo: string
+  options: Record<string, unknown>
+  jobIds: string[]
+}): Promise<{ logs: GitServiceApiExecutionResult<unknown>; selectedJobId: string; attempts: JobLogLookupAttempt[] }> => {
+  let lastResult: GitServiceApiExecutionResult<unknown> | null = null
+  let lastJobId = ''
+  const attempts: JobLogLookupAttempt[] = []
+
+  for (const jobId of params.jobIds) {
+    const logs = await requestGitea(
+      params.ctx,
+      ['actions', 'jobs', 'logs'],
+      params.owner,
+      params.repo,
+      'GET',
+      ['jobs', jobId, 'logs'],
+      params.options,
+    )
 
-  try {
-    ctx.log?.(`actions:http:request ${method.toUpperCase()} ${url.toString()}`)
-    const response = await fetch(url.toString(), {
-      method: method.toUpperCase(),
-      headers,
-      ...(timeoutSignal ? { signal: timeoutSignal } : {}),
-      ...(controller ? { signal: controller.signal } : {}),
-      ...requestInitOverrides,
+    attempts.push({
+      jobId,
+      status: logs.status,
+      ok: logs.ok,
+      message: extractErrorMessage(logs.body),
     })
 
-    const body = await readBody(response)
-    const responseHeaders: Record<string, string> = {}
-    try {
-      response.headers.forEach((value, key) => {
-        responseHeaders[key.toLowerCase()] = value
-      })
-    } catch {
-      // best effort
-    }
+    lastResult = logs
+    lastJobId = jobId
 
-    const mapping: GitApiFeatureMapping = {
-      platform: 'GITEA',
-      featurePath,
-      mappedPath,
-      method: method.toUpperCase(),
-      query: toQueryArray(queryRecord),
-      headers: headersList,
-      apiBase,
-      swaggerPath: `/${mappedPath.join('/')}`,
-      mapped: true,
-      reason: 'Direct Gitea Actions API call',
+    if (logs.ok && logs.status < 400) {
+      return { logs, selectedJobId: jobId, attempts }
     }
 
-    return {
-      mapping,
-      request: {
-        url: url.toString(),
-        method: method.toUpperCase(),
-        headers,
-        query: toQueryArray(queryRecord),
-      },
-      response: {
-        headers: responseHeaders,
-      },
-      status: response.status,
-      ok: response.ok,
-      body,
+    if (!shouldTryNextJobIdCandidate(logs.status)) {
+      return { logs, selectedJobId: jobId, attempts }
     }
-  } finally {
-    if (timeoutId) {
-      clearTimeout(timeoutId)
-    }
-  }
-}
-
-const tailText = (input: string, options: { contains?: string; maxLines?: number; maxBytes?: number }): string => {
-  const contains = toTrimmedString(options.contains ?? null) ?? null
-  const maxLines = toPositiveInteger(options.maxLines) ?? DEFAULT_LOG_TAIL_LINES
-  const maxBytes = toPositiveInteger(options.maxBytes)
-
-  let text = input
-
-  if (contains) {
-    text = text
-      .split(/\r?\n/g)
-      .filter((line) => line.includes(contains))
-      .join('\n')
-  }
-
-  if (maxLines > 0) {
-    const lines = text.split(/\r?\n/g)
-    text = lines.slice(Math.max(0, lines.length - maxLines)).join('\n')
   }
 
-  if (maxBytes && maxBytes > 0) {
-    const buf = Buffer.from(text, 'utf8')
-    if (buf.length > maxBytes) {
-      text = buf.subarray(buf.length - maxBytes).toString('utf8')
-    }
+  if (lastResult) {
+    return { logs: lastResult, selectedJobId: lastJobId, attempts }
   }
 
-  return text
+  throw new Error('No job id candidates were available for log lookup.')
 }
 
 export type GitActionsHelpBody = {
   summary: string
   suggestedCalls: Array<{
-    tool: string
-    args: string[]
-    options?: Record<string, unknown>
-    notes?: string
-  }>
-  assumptions: string[]
-}
-
-export const createGitActionsApi = (api: GitServiceApi, ctx: GitActionsApiContext): Record<string, GitServiceApiMethod> => {
-  const defaults = ctx.defaults ?? {}
-
-  return {
-    helpActionsLogs: async (): Promise<GitServiceApiExecutionResult<GitActionsHelpBody>> => {
-      const body: GitActionsHelpBody = {
-        summary:
-          'Use actions.tasks.list to locate the failing run, then actions.jobs.logsTail to pull the last N lines of job logs.',
-        suggestedCalls: [
-          {
-            tool: 'repo.actions.tasks.list',
-            args: ['<owner>', '<repo>'],
-            options: { query: { limit: 50 } },
-            notes: 'Filter client-side by head_sha and run_number from the response.',
-          },
-          {
-            tool: 'repo.actions.jobs.logsTail',
-            args: ['<job_id>'],
-            options: { maxLines: 250 },
-            notes: 'If you have default owner/repo configured, you can pass only <job_id>.',
-          },
-          {
-            tool: 'repo.actions.jobs.logsForRunTail',
-            args: ['<head_sha>', '<run_number>'],
-            options: { maxLines: 250 },
-            notes: 'Convenience helper: resolves a run from tasks and then fetches logs (assumes run.id is job_id).',
-          },
-        ],
-        assumptions: [
-          'Gitea exposes job logs at GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs.',
-          'This helper assumes ActionTask.id can be used as job_id for the logs endpoint. If that is false in your Gitea version, use the UI to find the job_id.',
-        ],
-      }
-
-      const mapping: GitApiFeatureMapping = {
-        platform: 'GITEA',
-        featurePath: ['help', 'actionsLogs'],
-        mappedPath: ['help', 'actionsLogs'],
-        method: 'GET',
-        query: [],
-        headers: ['Accept: application/json'],
-        apiBase: buildApiBase(ctx.config.giteaHost),
-        swaggerPath: '/help/actionsLogs',
-        mapped: true,
-        reason: 'Local help content',
-      }
-
-      return {
-        mapping,
-        request: {
-          url: 'local://help/actionsLogs',
-          method: 'GET',
-          headers: {},
-          query: [],
-        },
-        response: {
-          headers: {},
-        },
-        status: 200,
-        ok: true,
-        body,
-      }
-    },
-
-    tasks: async (ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown) => {
-      const parsed = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
-      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
-      return requestGitea(ctx, ['actions', 'tasks', 'list'], owner, repo, 'GET', ['tasks'], parsed.options)
-    },
-
-    jobsLogs: async (...rawArgs: unknown[]) => {
-      const resolved = resolveOwnerRepoAndId(rawArgs, defaults)
-      return requestGitea(
-        ctx,
-        ['actions', 'jobs', 'logs'],
-        resolved.owner,
-        resolved.repo,
-        'GET',
-        ['jobs', resolved.id, 'logs'],
-        resolved.options,
-      )
-    },
-
-    jobsLogsTail: async (...rawArgs: unknown[]) => {
-      const resolved = resolveOwnerRepoAndId(rawArgs, defaults)
-      const result = await requestGitea(
-        ctx,
-        ['actions', 'jobs', 'logs'],
-        resolved.owner,
-        resolved.repo,
-        'GET',
-        ['jobs', resolved.id, 'logs'],
-        resolved.options,
-      )
-
-      const asText = typeof result.body === 'string' ? result.body : JSON.stringify(result.body, null, 2)
-      const tailed = tailText(asText, {
-        contains: resolved.options.contains,
-        maxLines: resolved.options.maxLines,
-        maxBytes: resolved.options.maxBytes,
-      })
-
-      return {
-        ...result,
-        body: tailed,
-      }
-    },
-
+    tool: string
+    args: string[]
+    options?: Record<string, unknown>
+    notes?: string
+  }>
+  assumptions: string[]
+}
+
+export const createGitActionsApi = (api: GitServiceApi, ctx: GitActionsApiContext): Record<string, GitServiceApiMethod> => {
+  const defaults = ctx.defaults ?? {}
+
+  return {
+    helpActionsLogs: async (): Promise<GitServiceApiExecutionResult<GitActionsHelpBody>> => {
+      const body: GitActionsHelpBody = {
+        summary:
+          'Use actions.tasks.list to locate the failing run, then actions.jobs.logsTail to pull the last N lines of job logs.',
+        suggestedCalls: [
+          {
+            tool: 'repo.actions.tasks.list',
+            args: ['<owner>', '<repo>'],
+            options: { query: { limit: 50 } },
+            notes: 'Filter client-side by head_sha and run_number from the response.',
+          },
+          {
+            tool: 'repo.actions.jobs.logsTail',
+            args: ['<job_id>'],
+            options: { maxLines: 250 },
+            notes: 'If you have default owner/repo configured, you can pass only <job_id>.',
+          },
+          {
+            tool: 'repo.actions.jobs.logsForRunTail',
+            args: ['<head_sha>', '<run_number>'],
+            options: { maxLines: 250 },
+            notes: 'Convenience helper: resolves a run from tasks and then fetches logs (assumes run.id is job_id).',
+          },
+        ],
+        assumptions: [
+          'Gitea exposes job logs at GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs.',
+          'This helper assumes ActionTask.id can be used as job_id for the logs endpoint. If that is false in your Gitea version, use the UI to find the job_id.',
+        ],
+      }
+
+      const mapping: GitApiFeatureMapping = {
+        platform: 'GITEA',
+        featurePath: ['help', 'actionsLogs'],
+        mappedPath: ['help', 'actionsLogs'],
+        method: 'GET',
+        query: [],
+        headers: ['Accept: application/json'],
+        apiBase: buildApiBase(ctx.config.giteaHost),
+        swaggerPath: '/help/actionsLogs',
+        mapped: true,
+        reason: 'Local help content',
+      }
+
+      return {
+        mapping,
+        request: {
+          url: 'local://help/actionsLogs',
+          method: 'GET',
+          headers: {},
+          query: [],
+        },
+        response: {
+          headers: {},
+        },
+        status: 200,
+        ok: true,
+        body,
+      }
+    },
+
+    tasks: async (ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown) => {
+      const parsed = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
+      return requestGitea(ctx, ['actions', 'tasks', 'list'], owner, repo, 'GET', ['tasks'], parsed.options)
+    },
+
+    jobsLogs: async (...rawArgs: unknown[]) => {
+      const resolved = resolveOwnerRepoAndId(rawArgs, defaults)
+      return requestGitea(
+        ctx,
+        ['actions', 'jobs', 'logs'],
+        resolved.owner,
+        resolved.repo,
+        'GET',
+        ['jobs', resolved.id, 'logs'],
+        resolved.options,
+      )
+    },
+
+    jobsLogsTail: async (...rawArgs: unknown[]) => {
+      const resolved = resolveOwnerRepoAndId(rawArgs, defaults)
+      const result = await requestGitea(
+        ctx,
+        ['actions', 'jobs', 'logs'],
+        resolved.owner,
+        resolved.repo,
+        'GET',
+        ['jobs', resolved.id, 'logs'],
+        resolved.options,
+      )
+
+      const asText = typeof result.body === 'string' ? result.body : JSON.stringify(result.body, null, 2)
+      const tailed = tailText(asText, {
+        contains: resolved.options.contains,
+        maxLines: resolved.options.maxLines,
+        maxBytes: resolved.options.maxBytes,
+      })
+
+      return {
+        ...result,
+        body: tailed,
+      }
+    },
+
     jobsLogsForRunTail: async (headSha: unknown, runNumber: unknown, maybeOptions?: unknown) => {
       const sha = toTrimmedString(headSha)
       const run = toPositiveInteger(runNumber)
       const options = isRecord(maybeOptions) ? (maybeOptions as Record<string, unknown>) : {}
-
-      if (!sha || !run) {
-        throw new Error('headSha (string) and runNumber (positive integer) are required.')
-      }
-
-      const scope = normalizeScopeArgs(options.owner, options.repo, options)
-      const { owner, repo } = resolveOwnerRepo(scope, defaults)
-      const tasks = await requestGitea(ctx, ['actions', 'tasks', 'list'], owner, repo, 'GET', ['tasks'], scope.options)
-
-      const entries = isRecord(tasks.body) && Array.isArray(tasks.body.workflow_runs)
-        ? (tasks.body.workflow_runs as unknown[])
-        : []
-
-      const match = entries.find((entry) => {
-        if (!isRecord(entry)) return false
-        return String(entry.head_sha ?? '') === sha && Number(entry.run_number ?? NaN) === run
-      })
-
+
+      if (!sha || !run) {
+        throw new Error('headSha (string) and runNumber (positive integer) are required.')
+      }
+
+      const scope = normalizeScopeArgs(options.owner, options.repo, options)
+      const { owner, repo } = resolveOwnerRepo(scope, defaults)
+      const tasks = await requestGitea(ctx, ['actions', 'tasks', 'list'], owner, repo, 'GET', ['tasks'], scope.options)
+
+      const entries = isRecord(tasks.body) && Array.isArray(tasks.body.workflow_runs)
+        ? (tasks.body.workflow_runs as unknown[])
+        : []
+
+      const match = entries.find((entry) => {
+        if (!isRecord(entry)) return false
+        return String(entry.head_sha ?? '') === sha && Number(entry.run_number ?? NaN) === run
+      })
+
       if (!match || !isRecord(match)) {
-        throw new Error(`No matching run found in actions/tasks for head_sha=${sha} run_number=${run}.`)
+        throw new Error(
+          `No matching run found in actions/tasks for head_sha=${sha} run_number=${run}. Verify the run exists, then use repo.actions.tasks.list { owner, repo, query:{ limit: 100 } } to locate a valid run_number and job id.`,
+        )
       }
 
-      const jobId = match.id
-      const jobIdText = toTrimmedString(jobId)
-      if (!jobIdText) {
-        throw new Error('Matched run entry does not expose an id usable as job_id.')
+      const runEntry = match as Record<string, unknown>
+      const jobIdCandidates = collectJobIdCandidates(runEntry)
+      if (jobIdCandidates.length === 0) {
+        const keys = Object.keys(match).slice(0, 32).join(',')
+        const preview = (() => {
+          try {
+            return JSON.stringify(match).slice(0, 500)
+          } catch {
+            return ''
+          }
+        })()
+        throw new Error(
+          `Matched run entry does not expose a usable job id field (job_id/jobId/task_id/taskId/id). keys=[${keys}] preview=${preview}. Use repo.actions.jobs.logsTail with an explicit job_id from the Gitea UI or from tasks metadata.`,
+        )
       }
 
-      const logs = await requestGitea(
+      const maxLines = toPositiveInteger(scope.options.maxLines) ?? DEFAULT_LOG_TAIL_LINES
+      const lookup = await fetchJobLogsByCandidates({
         ctx,
-        ['actions', 'jobs', 'logs'],
         owner,
         repo,
-        'GET',
-        ['jobs', jobIdText, 'logs'],
-        scope.options,
-      )
+        options: scope.options,
+        jobIds: jobIdCandidates,
+      })
 
-      const asText = typeof logs.body === 'string' ? logs.body : JSON.stringify(logs.body, null, 2)
+      if (!lookup.logs.ok || lookup.logs.status >= 400) {
+        return {
+          ...lookup.logs,
+          body: buildJobLogsFailureBody({
+            owner,
+            repo,
+            headSha: sha,
+            runNumber: run,
+            attempts: lookup.attempts,
+            upstreamBody: lookup.logs.body,
+            maxLines,
+          }),
+        }
+      }
+
+      const asText =
+        typeof lookup.logs.body === 'string'
+          ? lookup.logs.body
+          : JSON.stringify(lookup.logs.body, null, 2)
       const tailed = tailText(asText, {
         contains: scope.options.contains,
         maxLines: scope.options.maxLines,
@@ -519,98 +740,246 @@ export const createGitActionsApi = (api: GitServiceApi, ctx: GitActionsApiContex
       })
 
       return {
-        ...logs,
+        ...lookup.logs,
         body: tailed,
       }
     },
-
-    artifacts: async (ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown) => {
-      const parsed = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
-      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
-      return requestGitea(ctx, ['actions', 'artifacts', 'list'], owner, repo, 'GET', ['artifacts'], parsed.options)
-    },
-
-    artifactsByRun: async (runId: unknown, ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown) => {
-      const id = toTrimmedString(runId)
-      if (!id) {
-        throw new Error('runId is required.')
+
+    diagnoseLatestFailure: async (ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown) => {
+      const parsed = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
+      // Allow calling with a single object payload: { owner, repo, workflowName, ... }.
+      const scope = normalizeScopeArgs(parsed.options.owner, parsed.options.repo, parsed.options)
+      const { owner, repo } = resolveOwnerRepo(scope, defaults)
+
+      const workflowNameRaw = typeof scope.options.workflowName === 'string' ? scope.options.workflowName.trim() : ''
+      const workflowName = workflowNameRaw.length > 0 ? workflowNameRaw : null
+      const maxLines = toPositiveInteger(scope.options.maxLines) ?? DEFAULT_LOG_TAIL_LINES
+      const maxBytes = toPositiveInteger(scope.options.maxBytes)
+      const contains = typeof scope.options.contains === 'string' ? scope.options.contains : undefined
+      const limit = toPositiveInteger(scope.options.limit) ?? 50
+
+      const baseQuery = isRecord(scope.options.query) ? (scope.options.query as Record<string, unknown>) : {}
+      const withLimitOptions = {
+        ...scope.options,
+        query: { ...baseQuery, limit },
       }
-      const parsed = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
-      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
-      return requestGitea(ctx, ['actions', 'runs', 'artifacts'], owner, repo, 'GET', ['runs', id, 'artifacts'], parsed.options)
-    },
 
-    artifactZipUrl: async (...rawArgs: unknown[]) => {
-      const resolved = resolveOwnerRepoAndId(rawArgs, defaults)
-
-      const result = await requestGitea(
+      let tasks = await requestGitea(
         ctx,
-        ['actions', 'artifacts', 'downloadZipUrl'],
-        resolved.owner,
-        resolved.repo,
+        ['actions', 'tasks', 'list'],
+        owner,
+        repo,
         'GET',
-        ['artifacts', resolved.id, 'zip'],
-        resolved.options,
-        { redirect: 'manual' },
+        ['tasks'],
+        withLimitOptions,
       )
 
-      const location =
-        typeof (result.response.headers.location) === 'string'
-          ? result.response.headers.location
-          : typeof (result.response.headers['location']) === 'string'
-            ? result.response.headers['location']
-            : null
+      if (!tasks.ok && (tasks.status >= 500 || tasks.status === 400 || tasks.status === 422)) {
+        const fallbackQuery = { ...baseQuery }
+        delete fallbackQuery.limit
+
+        tasks = await requestGitea(
+          ctx,
+          ['actions', 'tasks', 'list'],
+          owner,
+          repo,
+          'GET',
+          ['tasks'],
+          {
+            ...scope.options,
+            query: fallbackQuery,
+          },
+        )
+      }
 
-      return {
-        ...result,
-        body: {
-          status: result.status,
-          location,
-        },
+      const entries = isRecord(tasks.body) && Array.isArray(tasks.body.workflow_runs)
+        ? (tasks.body.workflow_runs as unknown[])
+        : []
+
+      const normalizedWorkflowName = workflowName ? workflowName.toLowerCase() : null
+      const failing = entries
+        .filter((entry) => isRecord(entry))
+        .filter((entry) => normalizeActionsState((entry as Record<string, unknown>).status) === 'failure')
+        .filter((entry) => {
+          if (!normalizedWorkflowName) return true
+          const name = String((entry as Record<string, unknown>).name ?? '').toLowerCase()
+          const displayTitle = String((entry as Record<string, unknown>).display_title ?? '').toLowerCase()
+          return name.includes(normalizedWorkflowName) || displayTitle.includes(normalizedWorkflowName)
+        })
+        .sort((a, b) => {
+          const aRecord = a as Record<string, unknown>
+          const bRecord = b as Record<string, unknown>
+          const aUpdated = Date.parse(String(aRecord.updated_at ?? '')) || 0
+          const bUpdated = Date.parse(String(bRecord.updated_at ?? '')) || 0
+          return bUpdated - aUpdated
+        })
+
+      const match = failing[0]
+      if (!match || !isRecord(match)) {
+        throw new Error(
+          workflowName
+            ? `No failing workflow run found matching workflowName=${workflowName}. Use repo.actions.tasks.list { owner, repo, query:{ limit: 100 } } and inspect workflow_runs[].name/display_title/status.`
+            : 'No failing workflow run found. Use repo.actions.tasks.list { owner, repo, query:{ limit: 100 } } and inspect workflow_runs[].status for failures.',
+        )
       }
-    },
-  }
-}
 
-const ensureNamespace = (root: GitServiceApi, path: string[]): GitServiceApi => {
-  let cursor: GitServiceApi = root
-  for (const segment of path) {
-    const current = cursor[segment]
-    if (!isRecord(current)) {
-      cursor[segment] = {}
-    }
-    cursor = cursor[segment] as GitServiceApi
-  }
-  return cursor
-}
+      const sha = String((match as Record<string, unknown>).head_sha ?? '').trim()
+      const run = toPositiveInteger((match as Record<string, unknown>).run_number)
+      if (!sha || !run) {
+        const preview = (() => {
+          try {
+            return JSON.stringify(match).slice(0, 500)
+          } catch {
+            return ''
+          }
+        })()
+        throw new Error(`Matched run entry is missing head_sha or run_number. preview=${preview}`)
+      }
 
-export const attachGitActionsApi = (api: GitServiceApi, ctx: GitActionsApiContext): void => {
-  const methods = createGitActionsApi(api, ctx)
-  const targets = [
-    ensureNamespace(api, ['actions']),
-    ensureNamespace(api, ['repo', 'actions']),
-    ensureNamespace(api, ['help']),
-    ensureNamespace(api, ['repo', 'help']),
-  ]
+      const runEntry = match as Record<string, unknown>
+      const jobIdCandidates = collectJobIdCandidates(runEntry)
+      if (jobIdCandidates.length === 0) {
+        const keys = Object.keys(runEntry).slice(0, 32).join(',')
+        throw new Error(
+          `Matched run entry does not expose a usable job id field (job_id/jobId/task_id/taskId/id). keys=[${keys}]. Use repo.actions.jobs.logsTail with an explicit job_id from the Gitea UI.`,
+        )
+      }
 
-  const mapping: Record<string, { to: string; description: string }> = {
-    helpActionsLogs: { to: 'actionsLogs', description: 'Help for fetching Gitea Actions job logs' },
-    tasks: { to: 'tasks.list', description: 'List repository action tasks (workflow runs)' },
-    jobsLogs: { to: 'jobs.logs', description: 'Download job logs for a workflow run job_id' },
-    jobsLogsTail: { to: 'jobs.logsTail', description: 'Download and tail job logs (bounded for LLM)' },
-    jobsLogsForRunTail: { to: 'jobs.logsForRunTail', description: 'Resolve run by sha+run_number and tail logs' },
-    artifacts: { to: 'artifacts.list', description: 'List repository artifacts' },
-    artifactsByRun: { to: 'runs.artifacts', description: 'List artifacts for a run' },
-    artifactZipUrl: { to: 'artifacts.downloadZipUrl', description: 'Return redirect URL for artifact zip download' },
-  }
+      const lookup = await fetchJobLogsByCandidates({
+        ctx,
+        owner,
+        repo,
+        options: scope.options,
+        jobIds: jobIdCandidates,
+      })
 
-  for (const target of targets) {
-    for (const [name, method] of Object.entries(methods)) {
-      const exportName = mapping[name]?.to ?? name
-      if (!(exportName in target)) {
-        target[exportName] = method
+      if (!lookup.logs.ok || lookup.logs.status >= 400) {
+        return {
+          ...lookup.logs,
+          body: buildJobLogsFailureBody({
+            owner,
+            repo,
+            headSha: sha,
+            runNumber: run,
+            workflowName,
+            attempts: lookup.attempts,
+            upstreamBody: lookup.logs.body,
+            maxLines,
+          }),
+        }
       }
-    }
-  }
-}
 
+      const asText =
+        typeof lookup.logs.body === 'string'
+          ? lookup.logs.body
+          : JSON.stringify(lookup.logs.body, null, 2)
+      const tailed = tailText(asText, {
+        contains,
+        maxLines,
+        ...(maxBytes ? { maxBytes } : {}),
+      })
+
+      return {
+        ...lookup.logs,
+        body: {
+          run: match,
+          logsTail: tailed,
+          owner,
+          repo,
+          headSha: sha,
+          runNumber: run,
+          jobId: lookup.selectedJobId,
+        },
+      }
+    },
+
+    artifacts: async (ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown) => {
+      const parsed = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
+      return requestGitea(ctx, ['actions', 'artifacts', 'list'], owner, repo, 'GET', ['artifacts'], parsed.options)
+    },
+
+    artifactsByRun: async (runId: unknown, ownerOrOptions?: unknown, repoOrOptions?: unknown, maybeOptions?: unknown) => {
+      const id = toTrimmedString(runId)
+      if (!id) {
+        throw new Error('runId is required.')
+      }
+      const parsed = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
+      return requestGitea(ctx, ['actions', 'runs', 'artifacts'], owner, repo, 'GET', ['runs', id, 'artifacts'], parsed.options)
+    },
+
+    artifactZipUrl: async (...rawArgs: unknown[]) => {
+      const resolved = resolveOwnerRepoAndId(rawArgs, defaults)
+
+      const result = await requestGitea(
+        ctx,
+        ['actions', 'artifacts', 'downloadZipUrl'],
+        resolved.owner,
+        resolved.repo,
+        'GET',
+        ['artifacts', resolved.id, 'zip'],
+        resolved.options,
+        { redirect: 'manual' },
+      )
+
+      const location =
+        typeof (result.response.headers.location) === 'string'
+          ? result.response.headers.location
+          : typeof (result.response.headers['location']) === 'string'
+            ? result.response.headers['location']
+            : null
+
+      return {
+        ...result,
+        body: {
+          status: result.status,
+          location,
+        },
+      }
+    },
+  }
+}
+
+const ensureNamespace = (root: GitServiceApi, path: string[]): GitServiceApi => {
+  let cursor: GitServiceApi = root
+  for (const segment of path) {
+    const current = cursor[segment]
+    if (!isRecord(current)) {
+      cursor[segment] = {}
+    }
+    cursor = cursor[segment] as GitServiceApi
+  }
+  return cursor
+}
+
+export const attachGitActionsApi = (api: GitServiceApi, ctx: GitActionsApiContext): void => {
+  const methods = createGitActionsApi(api, ctx)
+  const targets = [
+    ensureNamespace(api, ['actions']),
+    ensureNamespace(api, ['repo', 'actions']),
+    ensureNamespace(api, ['help']),
+    ensureNamespace(api, ['repo', 'help']),
+  ]
+
+  const mapping: Record<string, { to: string; description: string }> = {
+    helpActionsLogs: { to: 'actionsLogs', description: 'Help for fetching Gitea Actions job logs' },
+    tasks: { to: 'tasks.list', description: 'List repository action tasks (workflow runs)' },
+    jobsLogs: { to: 'jobs.logs', description: 'Download job logs for a workflow run job_id' },
+    jobsLogsTail: { to: 'jobs.logsTail', description: 'Download and tail job logs (bounded for LLM)' },
+    jobsLogsForRunTail: { to: 'jobs.logsForRunTail', description: 'Resolve run by sha+run_number and tail logs' },
+    diagnoseLatestFailure: { to: 'diagnoseLatestFailure', description: 'Find latest failing run and return log tail' },
+    artifacts: { to: 'artifacts.list', description: 'List repository artifacts' },
+    artifactsByRun: { to: 'runs.artifacts', description: 'List artifacts for a run' },
+    artifactZipUrl: { to: 'artifacts.downloadZipUrl', description: 'Return redirect URL for artifact zip download' },
+  }
+
+  for (const target of targets) {
+    for (const [name, method] of Object.entries(methods)) {
+      const exportName = mapping[name]?.to ?? name
+      if (!(exportName in target)) {
+        target[exportName] = method
+      }
+    }
+  }
+}